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.
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 (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.
build succeeded.
Build finished. The HTML pages are in _build/html.
Consider using semantic line breaks in your Sphinx files.
This is a paragraph that contains `a link`_.
If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text.
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
The :ref: role would then generate a link to the section, with the link title being “Section to cross-reference”. This works just as well when section and reference are in different source files.
a reference :ref:`my-figure` would insert a reference to the figure with link text “Figure caption”.
The same works for tables that are given an explicit caption using the table directive.
Labels that aren’t placed before a section title can still be referenced to, but you must give the link an explicit title, using this syntax: :ref:`Link title <label-name>`.
Inter-Sphinx links are enabled between the tools docs and the docs repo; i.e. whenever Sphinx encounters a cross-reference that has no matching target in the tools docs, it looks for targets in the docs, and vice-versa.
Using ref is advised over standard reStructuredText links to sections (like `Section title`_) because it works across files, when section headings are changed, and for all builders that support cross-references.
* `SalishSeaBathy.ipynb`_: Documents the full domain bathymetry used for the Salish Sea NEMO runs.
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.
The |br| substitution needs to be defined once (but only once) per file.
© Copyright 2013-2019, Salish Sea MEOPAR Project Contributors and The University of British Columbia Revision 43d765da507e.
Built with Sphinx using a theme provided by Read the Docs.
Free document hosting provided by Read the Docs.
