Notes from 11-Mar-2021 Sphinx documentation tutorial for MOAD group members.
environment.yaml
is a conda environment description that includes the packages discussed in the tutorial
MOAD docs about using Sphinx: https://ubc-moad-docs.readthedocs.io/en/latest/sphinx_docs.html
Sphinx docs, official and detailed: https://www.sphinx-doc.org/en/master/
Eric Holscher's Sphinx and Read the Docs tutorial, a little old, but includes a great reStructuredText cheat sheet: https://sphinx-tutorial.readthedocs.io/
Chris Holdgraf's Zero to Docs tutorial, less complete than Eric's, but a different take: https://docathon.github.io/zero_to_docs/index.html
Docs for nbsphinx
extension to parser Jupyter Notebooks into pages in Sphinx docs:
https://nbsphinx.readthedocs.io/en/0.8.2/
Docs for MyST parser that using extended Markdown syntax in Sphinx, new-ish, not enabled in any of our docs repositories (yet?): https://myst-parser.readthedocs.io/en/latest/index.html
make html
)firefox _build/html/index.html
)git add
and git commit
git push
to GitHubmake linkcheck
)git pull
and make html
(and some other stuff)something.readthedocs.io
Sphinx docs about rST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
index.rst
Files & TOC Trees¶index.rst
files in each directory contain toctree
directives that contain
lists of .rst
(and perhaps .ipynb
) files that the pages of the section***
above and below for top (1st) level heading===
below for 2nd level heading---
below for 3rd level heading~~~
below for 4th level heading*foo*
for emphasis; usually renders as italicized**foo**
for bold``foo``
for special literal highlighting, but consider using a semantic role (below) instead*
or -
for bullet (aka unordered) lists; need to indent if list item is >1 line long1.
, 2.
, or a.
, b.
for enumerated lists; #.
does automatic numberingSphinx docs about roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html
Sphinx docs about directives: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html
Sorry for so few examples here. The different meanings of backticks (`) in Markdown and rST make it difficult to write examples of one in the other.
:sup:
, :sub:
:ref:
:math:
role for inline math.. math::
directive for display mathHere are a few of the ones commonly used in our docs. There are more in the Sphinx docs.
:command:
for operating system level commands;
e.g. rm
, ssh --N -L 4343:salish:8888 salish
:kbd:
for a series of keystrokes; renders in a monospace font
I often (ab)use this for host names and the like that don't fall
into another semantic category:file:
for directory or file names:guilabel:
for graphical user interface (GUI) elements like buttons:menuselection:
for sequences of GUI menu selections:program:
for the names of programs like Matlab
or Word
.. toctree::
every index.rst
file needs one.. code-block::
for syntax highlighted code in many, many languages
(the list of languages that can be handled is astonishingFor terminal output, for example.
::
at the end of a line, or on a line by itself
displays the following indented text as literal text in a monospace font.. code-block:: text
can be used as a more explicit alternative to ::
on a line by itself