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

Table Of Contents

Previous topic

Initial Group Scheduling Tutorial Sequence

Next topic

Remote Testbed Access

This Page