Working with CAM documentation on github and sphinx

Getting Started

The CAM 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 CAM documentation is stored in the gh-pages branch of the NCAR/CAM repository. The sphinx generated HTML pages are accessible from URL http://ncar.github.io/CAM/doc/build/html/index.html

Here are the steps for working with the NCAR/CAM 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/NCAR/CAM.git

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

• generate the html pages using sphinx by running make in the ~/CAM/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 ~/CAM/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://ncar.github.io/CAM/doc/build/html/index.html] (https://ncar.github.io/CAM/doc/build/html/index.html)

Avoiding Conflicts

• Feel free to generate the html locally as often as you want, but do not commit the regenerated html yet

• When you're finished with your changes, from the doc subdirectory:

  git checkout -- doc/build
  

this resets the generated html to whatever it was on the remote

• Do the following in rapid succession to avoid conflicts:

  git pull
  make html
  git add ...
  git commit -m "Update html"
  git push
  

---

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