Documentation with Sphinx
direct rendering to HTML for online publication
easy inclusion of figures, graphs, and images
easy inclusion of Jupyter Notebooks
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
or in the
docs/ directory of code repositories
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
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.
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/ in this repository,
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
You can use your browser to open the
index.html file in that directory to preview them.
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.
The top level
docs/ directory contains
and the directory
After the docs have been built it will also contain the
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.
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 =========== =================================================== ============== ==================
The |br| substitution needs to be defined once (but only once) per file.