Documentation with Sphinx

We use Sphinx for most documentation in the UBC-MOAD projects and repositories. Sphinx provides:

  • direct rendering to HTML for online publication

  • easy inclusion of LaTeX math syntax with in-browser rendering via MathJax

  • easy inclusion of figures, graphs, and images

  • easy inclusion of Jupyter Notebooks

  • deep linkability

  • high search engine discoverability for docs that we publish to readthedocs

  • optional PDF rendering

LaTeX should be used for manuscripts of papers and theses, and for reports for which PDFs must be rendered, uploaded, and linked into other documentation to make them available online.

All documentation is under Version Control with Git and stored in either docs repositories (e.g. UBC-MOAD/docs, SalishSeaCast/docs , and MIDOSS/docs) or in the docs/ directory of code repositories (e.g. UBC-MOAD/moad_tools, or SalishSeaCast/NEMO-Cmd).

Most of our repositories are configured so that when changes that have been committed and pushed to GitHub a signal is sent to readthedocs.org to automatically rebuild and render the docs at a readthedocs.io sub-domain. There is a very good chance that you are presently reading the result of that processing pipeline at https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html#documentation-with-sphinx.

Links to a repository’s docs can generally be found in the README.

Sphinx uses reStructuredText (reST), a simple, unobtrusive markup language. The Sphinx documentation provides a brief introduction to reST concepts and syntax. Sphinx extends reST with a collection of directives and interpreted text roles for cross-referencing, tables of contents, code examples, and specially formatted paragraphs like notes, alerts, warnings, etc.

Installing Sphinx

To use Sphinx you need to have the sphinx and sphinx_rtd_theme packages installed in your conda environment. If you want to include Jupyter Notebooks in your docs you also need the nbsphinx package.

Our docs and code repositories docs all have a section about contributing or package development that includes details of how to setup up a conda environment to work in, and how to build, preview, and link-check the repository’s docs. For this repository please see Contributing to These Docs. moad_tools Package Development is an example of a code repository package development docs sections that includes information about working on its docs.

Building and Previewing Documentation

As you are writing and editing Sphinx documentation you can build the HTML rendered docs locally and preview them in your browser to ensure that there are no reST syntax errors and that the docs look the way you want them to.

In the top level docs/ directory (e.g. docs/ in this repository, or the docs/ sub-directory in a code repository) use the command:

make clean html

to build the docs. You will be notified of any syntax or consistency errors.

The HTML pages produced by the make clean html command are stored in the _build/html/ sub-directory. You can use your browser to open the index.html file in that directory to preview them. The command:

firefox _build/html/index.html

will probably do the right thing. You can keep a browser tab open to the rendered docs and refresh after each build to see updates.

Note

The top level docs/ directory contains (at minimum) the files conf.py, Makefile, and index.rst, and the directory _static/. After the docs have been built it will also contain the _build/ sub-directory.

The result of running make clean html should look something like:

Removing everything under '_build'...
Running Sphinx v3.5.2
making output directory... done
loading intersphinx inventory from https://ubc-moad-tools.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://nemo-cmd.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://salishseacmd.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://salishsea-meopar-docs.readthedocs.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 20 source files that are out of date
updating environment: [new config] 20 added, 0 changed, 0 removed
reading sources... [100%] zzz_archival_docs/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] zzz_archival_docs/index
generating indices... done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Writing Style

Please consider using semantic line breaks in your Sphinx files. Doing so makes it easier to quickly rearrange clauses and ideas as you edit and revise. It also makes it so much easier to see changes in context when you use git diff or look at commits on GitHub.

Forcing Line Breaks

In most cases your should just let Sphinx take care of inserting line breaks in the rendered docs; it will almost always do the right thing by putting breaks between paragraphs, between list items, around block quotations and code examples, etc.

Occasionally though you may need to force line breaks. The most common case for this is to add line breaks within table cells so as as to avoid excessive sideways scrolling of the rendered table. You can force a line break in the HTML that Sphinx renders by defining a substitution that will insert a break tag (<br>). Here’s an example of doing that and using the substitution in a table cell:

.. |br| raw:: html

    <br>

===========  ===================================================  ==============  ==================
 Date                       Change                                New Value       Changeset
===========  ===================================================  ==============  ==================
27-Oct-2014  1st :file:`nowcast/` run results                     N/A
20-Nov-2014  1st :file:`forecast/` run results                    N/A
26-Nov-2014  Changed to tidal forcing tuned for better |br|       see changeset   efa8c39a9a7c_
             accuracy at Point Atkinson
===========  ===================================================  ==============  ==================

Note

The |br| substitution needs to be defined once (but only once) per file.