Other docs/primer

Table Of Contents

Previous topic

Build Instructions for Sphinx based documentation

Next topic

Autodoc : pulling reStructuredText from docstrings

This Page

Daya Bay Links

Content Skeleton

Sphinx Customizations/Primer

The general usage of Sphinx and reStructuredText are well documented:

This document covers customizations made for the Offline User Manual and the features these customizations provide. Use the Show Source links in the html sidebar of every page to see more usage examples.


A facility for simple linking to objects (in a very general sense) from other Sphinx documented projects is implemented in the extension module sphinx.ext.intersphinx This for example allows inline linking to a python class zipfile.ZipFile and a matplotlib module matplotlib.pyplot without specifying the precise target URL.

Spelling out the source (also use the):

reST source render
:py:mod:`sphinx.ext.intersphinx` sphinx.ext.intersphinx
:mod:`sphinx.ext.intersphinx` sphinx.ext.intersphinx
:py:class:`zipfile.ZipFile` zipfile.ZipFile
:py:mod:`matplotlib.pyplot` matplotlib.pyplot
:meth:`matplotlib.pyplot.acorr` matplotlib.pyplot.acorr()
:mod:`numpy` numpy
:class:`numpy.ndarray` numpy.ndarray
:rst:dir:`math` math
:rst:role:`math` math
:rst:directive:`math` FAILS

Note that the :py: is not strictly needed as py is the default domain.

This is configured in conf.py with:

intersphinx_cache_limit = 10     # days to keep the cached inventories
intersphinx_mapping = {
        'sphinx': ('http://sphinx.pocoo.org',  None),
    'matplotlib':('http://matplotlib.sourceforge.net', None),

Object Inventories

A simple script to dump the content of intersphinx inventories is at docs/inventory.py. Use it to find reference targets, for example:

./docs/inventory.py sphinx | grep reStructured
   rst-primer = (u'Sphinx', u'1.0.6', u'./docs/inv/sphinx/objects.inv/rest.html#rst-primer', u'reStructuredText Primer')

./docs/inventory.py sphinx std:label
   basic-domain-markup = (u'Sphinx', u'1.0.6', u'./docs/inv/sphinx/objects.inv/domains.html#basic-domain-markup', u'Basic Markup')
   build-config = (u'Sphinx', u'1.0.6', u'./docs/inv/sphinx/objects.inv/config.html#build-config', u'The build configuration file')
   builders = (u'Sphinx', u'1.0.6', u'./docs/inv/sphinx/objects.inv/builders.html#builders', u'Available builders')
   builtin-themes = (u'Sphinx', u'1.0.6', u'./docs/inv/sphinx/objects.inv/theming.html#builtin-themes', u'Builtin themes')

./docs/inventory.py self std:label     ## "self" refers to the Offline User Manual inventory
    api-main = (u'Offline User Manual', u'0.1', u'./_build/dirhtml/objects.inv/api/main/#api-main', u'NuWa Python API')
    ch:framework = (u'Offline User Manual', u'0.1', u'./_build/dirhtml/objects.inv/framework/main/#ch-framework', u'Offline Framework')
    ch:source = (u'Offline User Manual', u'0.1', u'./_build/dirhtml/objects.inv/sourcecode/main/#ch-source', u'Installation and Working with the Source Code')

Shows that can refer to the primer as shown in the below table, labels begging std: are refered to with the ref role others use the dedicated role for the object type.

reST source render note
:ref:`rst-primer` rst-primer no need to specify sphinx
:ref:`invocation` invocation label from resolving inventory
:ref:`<sphinx:invocation>` <sphinx:invocation> specify inventory FAILS
:ref:`from sphinx<sphinx:invocation>` from sphinx my label, defines src proj

Graphviz Figures

Sphinx graphviz extension provides graphviz, graph and digraph , allowing source like:

.. digraph:: foo

   "bar" -> "baz" -> "quux";

To generates a figure:

digraph foo {
"bar" -> "baz" -> "quux";

For details see sphinx.ext.graphviz, for an intro take your pick from google:graphviz dot tutorial eg wikipedia:Dot_language