Working with Sphinx and reStructuredText

Getting Started

The CIME documentation is written in reStructuredText (a markup language, like HTML, markdown or latex; see the bottom for some helpful resources) and is converted to publishable website by Sphinx. Sphinx can also generate the documentation in many other formats, such as PDF and LaTeX.

The CIME documentation is stored in the doc/source directory of the ESMCI/cime repository, and Sphinx will generate the documentation into the doc/build directory. However, as noted below, we typically do an out-of-source build.

Note: the build directory is ignored and nothing below it should be committed to the repository.

To publish the documentation to http://esmci.github.io/cime/, the build process should be done using a method that generates the HTML website in an appropriate subdirectory of the orphan gh-pages CIME branch.

The next two sections describe how to work with and publish the documentation.

Working with the docs

Note: for the purposes of these instructions, we will refer to the local directory containing your developmental clone (or fork) of CIME as $CIME.

The CIME documentation is contained within the $CIME/doc/source directory. When developing a feature, the documentation can be updated accordingly (if needed) by editing the reStructuredText files in $CIME/doc/source, and an updated version of the documentation should be built to verify your changes.

To build the documentation, you will need to have sphinx installed on your local machine (see Installing sphinx for details). The easiest way to install sphinx is by using pip:

pip install -r $CIME/doc/requirements.txt

Note: you may need to update your PATH environment variable to include the path to the sphinx-build script. On a mac, the default location for this script is python-packages/bin/sphinx-build.

Then you can build a local copy of the documentation by navigating to $CIME/doc and issuing these commands:

make clean
make html

which will generate an HTML version of the website in $CIME/doc/build/html. You can view the documentation locally in your favorite web browser. (Note: make html will automatically run make api, which generates API documentation in-source. make clean cleans both the build directory and the in-source generated API documentation.)

Previewing the docs

If your feature branch is made from the ESMCI/cime repo and not a fork then a preview of the documentation will be generated and a url will be provided via a comment in the PR.

Publishing the docs

When a feature is complete and merged into master, the updated documentation will automatically be built and deployed by a Github Actions workflow.

Adding a new version

If you want to add a new version of the documentation, so that it appears in the dropdown menu, follow this process:

1. Check out the branch you want to build the documentation from.

git checkout <source branch>

2. Install the tools required to build the documentation.

pip install -r $CIME/doc/requirements.txt

3. Checkout the gh-pages branch using either clone or worktree.

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

or

git worktree add ../cime-gh-pages gh-pages

4. Update the version and release variables in doc/source/conf.py before building the docs.

5. Build the docs and output to the versions directory in the gh-pages branch. Replace <name> with the branch name.

make BUILDDIR=../../cime-gh-pages/versions/<name> -C doc/ html

6. Edit the versions.json file in the gh-pages branch. This is a dictionary mapping the directory name to the display name in the documentation. If test was used for <name> above and the display name should be Test then you would add an entry like "test": "Test", to the file.

cd ../cime-gh-pages
$EDITOR versions/versions.json

7. Commit your changes and push the branch.

git add .
git commit -m <commit message>
git push -u origin gh-pages

Generating PDF

Sphinx can generate a PDF version of the documentation using a module add-on as follows:

1. Install rst2pdf

• use your package manager (or)
• pip install rst2pdf (or)
• easy_install rst2pdf

2. Edit $CIME/doc/source/conf.py to add rst2pdf to the list of extensions:

• extensions = ['rst2pdf.pdfbuilder']
  • This list will be empty if you accepted the defaults when the project was setup. If not, just append rst2pdf.pdfbuilder to the list.

3. Add a pdf_documents variable to conf.py

• pdf_documents = [(master_doc, u'CIME_Users_Guide', u'CIME Users Guide (PDF)', u'list-of-authors'),]
  • For all supported options, please check The Rst2pdf Handbook. There is also a Sphinx related section towards the end of the manual.

4. Generate the PDF

• cd $CIME/doc
• sphinx-build -b pdf source build/pdf

The generated PDF will be in the $CIME/doc/build/pdf directory.

Note: for convenience, you can add this command to the $CIME/doc/Makefile (or make.bat on Windows)

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)