Documentation with Sphinx

We use Sphinx for most documentation in the Salish Sea MEOPAR project. 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
  • deep linkability
  • optional PDF rendering

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

All documentation is under Version Control with Mercurial and stored in either the docs repo, or in the docs directory of another appropriate project repo (see Organization of Mercurial Repositories). Most notably, the tools repo includes a large public documentation tree. When changes that have been committed to the docs and tools repos are pushed to Bitbucket a signal is sent to readthedocs.org to automatically rebuild and render the docs at https://salishsea-meopar-docs.readthedocs.io/en/latest/ and https://salishsea-meopar-tools.readthedocs.io/en/latest/, respectively.

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

Sphinx and the packages that it depends on are included in the Anaconda Python Distribution that you should already have installed.

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 the docs repo, or tools/docs/ in the tools repo) use the command:

make html

to build the docs. You will be notified of any syntax or consistency errors. The HTML pages produced by the make html command are stored in the _build/html/ subdirectory and you can use your browser to open the index.html file in that directory to preview them. 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/ directory.

The result of running make html should look something like:

sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.1.3
loading pickled environment... done
building [html]: targets for 9 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] sphinx_docs
writing additional files... search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.

Writing Style

Consider using semantic line breaks in your Sphinx files.

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.