Documentation with Sphinx¶
- 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.
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.
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.
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 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.
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.