Documentation Using Sphinx

How to use Sphinx in creating a new KUSP document:

1. bash> mkdir <doc-dir>; svn add <doc-dir> ; svn commit -m"adding new doc"

2. bash> svn propset svn:ignore "build" <doc-dir>

3. bash> cd <doc-dir>; sphinx-quickstart

   • Lots and lots of answers, y mostly, default mostly
   • No to java-math and Windows makefile

4. add Directories, Paper option, and install targets to Makefile:

   LOCAL_ROOT   = ~/tmp/kusp_html
   PUBLIC_ROOT  = /projects/kurt/public_html
   DOC_ROOT     = kusp_docs/example_sigpipe_gs_ccsm
   
   PAPER         = $(PAPEROPT_letter)
   
   install: install-local
           @echo "Installed locally. Use 'make install-public' to install publically"
   
   install-local:
           -mkdir -p $(LOCAL_ROOT)/$(DOC_ROOT)
           -rsync -av build/html/* $(LOCAL_ROOT)/$(DOC_ROOT)
   
   install-public:
           -mkdir -p $(PUBLIC_ROOT)/$(DOC_ROOT)
           -rsync -av build/html/* $(PUBLIC_ROOT)/$(DOC_ROOT)
   
   #. copy KUSP logo to *<doc-dir>/source/_static*
   #. Add html themes and html logo in *<doc-dir>/source/conf.py* ::
   
   # Theme options are theme-specific and customize the look and feel of a theme
   # further.  For a list of options available for each theme, see the
   # documentation.
   #
   # footerbgcolor    : Background color for the footer line.
   # footertextcolor  : Text color for the footer line.
   # sidebarbgcolor   : Background color for the sidebar.
   # sidebartextcolor : Text color for the sidebar.
   # sidebarlinkcolor : Link color for the sidebar.
   # relbarbgcolor    : Background color for the relation bar.
   # relbartextcolor  : Text color for the relation bar.
   # relbarlinkcolor  : Link color for the relation bar.
   # bgcolor          : Body background color.
   # textcolor        : Body text color.
   # linkcolor        : Body link color.
   # headbgcolor      : Background color for headings.
   # headtextcolor    : Text color for headings.
   # headlinkcolor    : Link color for headings.
   # codebgcolor      : Background color for code blocks.
   # codetextcolor    : Default text color for code blocks,
   #                    if not set differently by the highlighting style.
   # bodyfont (CSS font-family): Font for normal text.
   # headfont (CSS font-family): Font for headings.
   
   html_theme_options = {
       "bgcolor"           : "#fff2b1",
       "textcolor"         : "#000000",
       "sidebarbgcolor"    : "#DFC297",
       "sidebartextcolor"  : "#601e0b",
       "sidebarlinkcolor"  : "#BA1E2A",
       "linkcolor"         : "#BA1E2A",
       "headlinkcolor"     : "#BA1E2A",
       "headbgcolor"       : "#D2AD72",
       "headtextcolor"     : "#5d240a",
       "codebgcolor"       : "#DFC297",
       "codetextcolor"     : "black",
       "relbarbgcolor"     : "#601e0b",
       "relbartextcolor"   : "#fff7be",
       "relbarlinkcolor"   : "#fff7be",
       "footerbgcolor"     : "#ffe6b2",
       "footertextcolor"   : "#601e0b"
   }
   
   html_logo = "_static/kusp_logo_round.png"

5. bash> cd <doc-dir> ; svn add source Makefile

6. bash> svn commit -m"initial version of new document"

7. Add <doc-dir> into its parent Makefile sub-document list

8. Add link to new document to KUSP Overview Document list

General observarions and advice:

1. Sphinx is very picky about section heading order. If it thinks you have gotten something wrong, this is a fatal error while generating HTML. In general, the KUSP documents have section headings at the level of “====”, with subsections underlined by “—–”, subsubsections underlined with “^” and paragraph titles emphasized by being surrounded by double stars and thus rendered bold.

Automatic Documentation Generation

There is a custom script located in the root of the kusp documentation tree named sphinx-kusp. This script automatically generates documentation with all of the above settings already established. To run the script, go to the root of the tree and do:

.bash$ ./sphinx-kusp