Sphinx Cheat Sheet

Docs build commands¶

Build the docs from the root of your project using any of the commands below. If you build from the docs/ directory, omit -C docs from the command.

make -C docs html            \\ one-time build
make -C docs preview         \\ live reload as you write
make -C docs docker-preview  \\ live reload as you write, built in a docker container

Table of Contents¶

Sphinx has a number of configuration options for tables of contents. A standard toctree directive is below.

.. toctree::
   :max-depth: 2

   doc1
   doc2
   doc3

Paragraph-level markup¶

Callouts¶

.. note:: Inserts a “note” content block.
.. tip:: Inserts a “tip” content block.
.. warning:: Inserts a “warning” content block.
..important:: Inserts an “important” content block.
.. seealso:: Inserts a “See also” content block.

Cross-references¶

:ref:`link text <section-label>` Use to insert a cross reference to a section, document, etc.

Example:

Sphinx Syntax

becomes Sphinx Syntax.

Showing Code Blocks¶

The Sphinx documentation covers code blocks extensively; we also mention them in the rST cheat sheet.

Inline Markup¶

The following can be useful when documenting commands and/or GUI tasks. See the sphinx inline markup documentation for more.

:command: The name of an OS-level command, such as rm.
:guilabel: Special markup for labels that appear in a GUI.
:menuselection:: Special markup for menu items/options that appear in a GUI. Separate the names of individual selections with -->.

File ‣ Open

becomes

File ‣ Open

Substitutions¶

Substitutions are especially helpful for product names, versions, commonly-used links, etc. To create a substitution you can use anywhere in the documentation set add an rst_epilog to the project’s conf.py:

# Substitutions
rst_epilog = """
.. |sub| replace:: Substituted Term
"""

Sidebar¶

The following directive produces the sidebar displayed at the top of this page.

.. sidebar:: Sphinx Directives

   Sphinx directives should always be on their own lines.
   The content to which the directive applies should be:

   - separated from the directive by a blank line
   - indented to line up with the beginning of the directive word

   .. parsed-literal::

      .. directivename:: argument ...
         :option: value

         Content of the directive.

Sphinx Cheat Sheet¶