Working with CESM documentation on github and sphinx

The CESM documentation is written using reStructuredText markup language. ReStructuredText is a markup language, like HTML, markdown or latex.

Sphinx is a python tool for publishing reStructuredText documents in other formats such as HTML and PDF.

The CESM documentation is stored in the gh-pages branch of the CESM-Development repository. The sphinx generated HTML pages are accessible from URL http://CESM-Development.github.io/cime/doc/build/html/index.html

Here are the steps for working with the CESM-Development documentation:

• make sure sphinx is installed on your local machine. See [Installing sphinx] (http://www.sphinx-doc.org/en/stable/install.html) for details.

• clone the gh-pages branch to your local machine

git clone -b gh-pages https://github.com/CESM-Development/cime.git

• edit the *.rst pages of interest in the ~/cime/doc/source directory

• generate the html pages using sphinx by running make in the ~/cime/doc directory Note: you may need to update your PATH environment variable to include the path to the sphinx-build script. On the mac, the default location for this script is:

python-packages/bin/sphinx-build

make html

• For Windows (to perform the make):

sphinx-build -b html sourcedir builddir

• view your changes in a local browser window using::

  open ~/cime/doc/build/html/index.html

• push just changes back to the github gh-pages branch.

git push origin gh-pages

The resulting URL with the html generated pages is:

[https://CESM-Development.github.io/cime/doc/build/html/index.html] (https://CESM-Development.github.io/cime/doc/build/html/index.html)

---

Here are some resources for learning markup with reStructuredText and using Sphinx.

• [reStructuredText Primer] (http://www.sphinx-doc.org/en/stable/rest.html)
• [ReST Syntax] (https://wiki.typo3.org/ReST_Syntax)
• [Sphinx (including how to get Sphinx)] (http://www.sphinx-doc.org/en/stable/)
• [reStructured syntax] (http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#tables)

For Mac users with Macports (CGD folks, IS will install it for you if you don't already have it), I recommend:

sudo port install py27-sphinx