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. The following command will create a CAM_docs directory for you. Note that you only need to do this one time, unless you delete the directory between edit sessions.

  git clone -b gh-pages https://github.com/NCAR/CAM.git CAM_docs

-------------- Start here if you have a previous CAM_docs directory ------------

• IMPORTANT - Sphinx is loaded on the CGD Linux machines, but users must load the updated python for it to work properly:

  module load lang/python/2.7.11

• Make sure your directory is up-to-date

  git pull

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

• generate the html pages using sphinx by running make in the ~/CAM_docs/doc directory. Do not commit the regenerated html. This will avoid conflicts in the generated html (see below for committing the html).

• For the scientific documentation you will need an installation of latex on your machine in order to interpret latex embedded equations

  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_docs/doc/build/html/index.html -OR-

  firefox ~/CAM_docs/doc/build/html/index.html -OR-

  konqueror ~/CAM_docs/doc/build/html/index.html

• When you're finished with your changes, from the directory which contains the Makefile, do the following to reset the generated html to whatever it was on the remote:

  make clean

  cd .. (to go back to the top level directory assuming you are in the doc subdirectory)

  git checkout -- doc/build

• Make sure that you are still up-to-date with repo:

  git pull

• Check for the status of your files:

  git status

• You will need to stage each of the identified files for your commit (they will be identified as either "Changes not staged for commit" or as "Untracked files" if they are new files) by doing this, e.g.:

  git add doc/source/users_guide/building-and-running-cam.rst

• Check the status once again for your files to make sure you got all of them

  git status

• Commit your changes:

  git commit -m "I fixed some things"

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

  git push origin gh-pages

You have now successfully committed your changes to the documentation.

Updating the html and doing so in a way to avoid conflicts

After you have committed your .rst changes above, you may want to update the html so that the web page reflects your changes. Otherwise, they will be posted whenever someone updates the html.

It is suggested that you make the html commits separate from the .rst commits. This allows you to clearly see the small number of files which you have directly modified (committed above) separate from the massive number of html-generated files (committed below)

• Move to the doc directory

  cd ~/CAM_docs/doc

• Remove the current modified html

  make clean

• Do the following in rapid succession to avoid conflicts. Note that generating the html at this stage takes significantly more time since you are starting from scratch after the make clean:

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

The URL with the snapshot of html generated pages is: (https://ncar.github.io/CAM/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