Sphinx Documentation Pointers

References Other Sections of the Documentation

To reference other sections in the documentation, an anchor must first be created above the target section:

.. _docs.example.reference:

Example Section Header
----------------------

NOTES:

#.  The reference anchor must start with an underscore, i.e. ``_``.

#.  !! There must be an empty line between the anchor and its target !!

The anchor can then be referenced elsewhere in the docs:

Referencing the section :ref:`docs.example.reference` from
another page in the docs.

Referencing the section with
:ref:`custom text <docs.example.reference>` from another page
in the docs.

Note that the prefix underscore is not needed when referencing the anchor.

Referencing the Source Code

The literalinclude directive can be used to display the source code inside a Sphinx document. To display the full file content:

.. literalinclude::  relative/path/from/this/rst/file/to/the/source.txt

To display only a section of the file, a pair of unique tags must first be added to the target source file, as comments with the tag string enclosed in brackets.

For Python source files:

# [example.tag.start]

# ... code section that will be referenced ...

# [example.tag.end]

For C++ source files:

/// @skipline [example.tag.start]

/// ... code section that will be referenced ...

/// @skipline [example.tag.end]

The tags then need to be supplied to the literalinclude directive:

.. literalinclude::  relative/path/from/this/rst/file/to/the/source.cpp
  :language: cpp
  :start-after: example.tag.start
  :end-before: example.tag.end

See the Sphinx documentation here for more information.

Adding LaTeX

Math expressions with LaTeX can be added inline to Sphinx docs using the math directive:

Example text: :math:`k_{n+1} = n^2 + k_n^2 - k_{n-1}`

The above example will be rendered as: \(k_{n+1} = n^2 + k_n^2 - k_{n-1}\).

Math expressinos can also be inserted as a code block:

.. math::

  \int_a^bu \frac{d^2v}{dx^2} \,dx
    = \left.u \frac{dv}{dx} \right|_a^b
    - \int_a^b \frac{du}{dx} \frac{dv}{dx} \,dx

\[\int_a^bu \frac{d^2v}{dx^2} \,dx = \left.u \frac{dv}{dx} \right|_a^b - \int_a^b \frac{du}{dx} \frac{dv}{dx} \,dx\]

See the Sphinx documentation here and here for more information.

Adding Graphs

Graphs can be generated in Sphinx using graphviz directive. Graph descriptions can be added inside a block:

.. graphviz::

  digraph example {
    "From" -> "To";
  }

Alternatively, they can be imported from an external .dot file:

.. graphviz:: ExampleGraph.dot

See the Sphinx and Graphviz documentation more information.