Skip to content

Directions for editing CLM documentation on github and sphinx

Jump to bottom
Keith Oleson edited this page Jan 31, 2018 · 56 revisions

Getting Started

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

Here are the steps for working with the ESCOMP/ctsm-docs documentation:

  • Official CIME github wiki is: https://github.com/ESMCI/cime/wiki/CIME-Git-Workflow
    NOTE: THE ABOVE DOCUMENT GIVES SOME ADVICE IN TERMS OF ONE TIME CONFIG SETTINGS YOU SHOULD DO ON EACH MACHINE YOU’LL BE USING. IF YOU DON’T CONFIGURE, GIT WILL COMPLAIN WITH EACH COMMIT. YOU SHOULDN'T HAVE TO WORRY ABOUT THIS IF YOU ARE WORKING ON CGD MACHINES

  • If you have access to the CGD systems, then you should use the CGD linux systems to do this work (redcloud.cgd.ucar.edu and thorodin.cgd.ucar.edu are known to work properly). If you don't have access, then you will need python/sphinx installed on your machine (see below). DO NOT USE yellowstone/cheyenne/geyser/caldera.

  • You can also get python/sphinx installed for your laptop. The document below tells you how, or you can get help from CGD ISG if you are at NCAR. https://github.com/ESMCI/cime/wiki/Getting-Started-with-Sphinx-and-reStructuredText

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

  • To load python/sphinx on CGD machines:

    module load lang/python/2.7.11

  • Get the current source from github by cloning the gh-pages branch to your local machine, this will create the directory CLM_Doc (note that the User's Guide as well as the Tech Note are in this repository). Note that you should only have to do this once. CLM_Doc will act as your sandbox.

    git clone -b gh-pages https://github.com/ESCOMP/ctsm-docs.git CLM_Doc

  • You will want to make sure you are up to date with changes made to gh-pages before you actually begin making your changes. To do this:

    git pull

    Note that a "git pull " command does both the fetch and the merge in one step as opposed to a "git fetch origin gh-pages" followed by a "git merge gh-pages".

  • Edit the *.rst pages of interest in the ~/CLM_Doc/doc/source/tech_note directories using a text editor as needed

  • You may generate the html pages locally using sphinx by running

    make html

    in the ~/CLM_Doc/doc directory as often as you want to view your changes, but do not commit the regenerated html. This will avoid conflicts in the generated html (see below for commit steps).
    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

  • For Windows (to perform the make):

    sphinx-build -b html sourcedir builddir

  • View your changes in a local browser window using:

    open ~/CLM_Doc/doc/build/html/index.html & OR firefox ~/CLM_Doc/doc/build/html/index.html & OR konqueror ~/CLM_Doc/doc/build/html/index.html &

  • When you're finished with your changes, from the top level directory 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/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst

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

    git status

  • Commit your changes:

    git commit -m "I fixed some things"

  • Push changes back to the github gh-pages branch.

    git push origin gh-pages

  • Notify Keith Oleson (oleson@ucar.edu) and he will generate and commit the html files

Once he's done, the resulting URL with the html generated pages is:

http://escomp.github.io/ctsm-docs/doc/build/html/index.html

  • To generate a pdf of the technical note

    cd doc

    make -f Makefile.tech_note latexpdf

    make -f Makefile.tech_note latexpdf

    The pdf will be here doc/build/tech_note/latex/clmdoc.pdf

  • To generate a pdf of the user's guide

    cd doc

    make -f Makefile.users_guide latexpdf

    make -f Makefile.users_guide latexpdf

    The pdf will be here build/users_guide/latex/clmdoc.pdf

    DO NOT COMMIT the pdf and associated files. Before committing, do a make clean (Note: this will also remove your html build). Then do a git checkout -- doc/build to reset the generated html to whatever it was on the remote.

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

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

Clone this wiki locally