Documentation Using Sphinx
===========================

How to use Sphinx in creating a new KUSP document:

#. ``bash> mkdir <doc-dir>; svn add <doc-dir> ; svn commit -m"adding new doc"``
#. ``bash> svn propset svn:ignore "build" <doc-dir>``
#. ``bash> cd <doc-dir>; sphinx-quickstart``

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

#. 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"

#. ``bash> cd <doc-dir> ; svn add source Makefile`` 
#. ``bash> svn commit -m"initial version of new document"``
#. Add <doc-dir> into its parent Makefile sub-document list
#. Add link to new document to KUSP Overview Document list 

General observarions and advice:


#. 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