Sphinx 101

ReST formatting

For details on basic rST formatting, see the reStructuredText Primer

  • emphasis, strong empasis, code

  • ``nesting`` *won’t* ``work``

  • roles are formatted as :rolename:`some text`. See Roles #. Numbered lists look like this

    1. or like this, and can be nested,
    2. as long as there is
    1. an empty line between the lists.
  • Definition lists

    have one line for the term, followed by one or more indented multiline paragraphs.

    Like this.

  • There must be a space between the link text and the url in hyperlinks.

  • Conventions for header markup:

    1. # with overline
    2. * with overline
    3. =
    4. -
    5. ^
    6. "

Roles

All other roles are added by Sphinx
Inline markup:
reStructured text:
:emphasis:, :strong:, :literal:, :subscript:, :superscript:, and :title-reference:.
extra in Sphinx:

:abbr:, :command:, :dfn:, :file:, :guilabel:, :kbd:, :menuselection:, :mimetype:, :program:, :regexp:, :samp:.

See Roles.

Generic cross-referencing:
Syntax:
  • :role:`target`
  • :role:`title <target>` displays title instead of the title provided by the reference.
  • :role:`!target` doesn’t create a reference/hyperlink (bit still includes the title provided by the reference).
  • :role:`~path.to.target` only displays the last segment of the target path.
:any:
:ref:
:doc:
:envvar:
:term:
:pep:
:rfc:
Python cross-referencing:
:mod:
:func:
:data:
:const:
:class:
:meth:
:attr:
:exc:
:obj:
Python info field lists:
:param str sender: The person sending the message
:param priority: The priority of the message, can be a number 1-5
:type priority: integer or None
:return: the message id
:rtype: int or None
:raises ValueError: if the message_body exceeds 160 characters
:raises TypeError: if the message_body is not a basestring

Container types can be linked automatically with the following syntax:

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]

Multiple types in a type field will be linked automatically if separated by the word or.

Directives

Explicit Markup Block
begins with a line starting with .. followed by whitespace and is terminated by the next paragraph at the same level of indentation.
Directives

are Explicit Markup with special semantics. Directives and roles form the extension mechanism of rST. Basically, a directive consists of a name, arguments, options and content:

.. name:: arg1
          arg2
    :option1: arg, arg
    :option2:

    Content

Directives are defined by

See Directives for documentation of many handy directives, such as:

.. note::
.. warning::
.. versionadded:: version
.. versionchanged:: version
.. deprecated:: version
.. seealso::
.. hlist::

Google-style docstrings

Example:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

The following section headers are supported:

  • Args (alias of Parameters)
  • Arguments (alias of Parameters)
  • Attributes
  • Example
  • Examples
  • Keyword Args (alias of Keyword Arguments)
  • Keyword Arguments
  • Methods
  • Note
  • Notes
  • Other Parameters
  • Parameters
  • Return (alias of Returns)
  • Returns
  • Raises
  • References
  • See Also
  • Todo (doesn’t work together with sphinx.ext.todo: items won’t show up in the .. todolist::)
  • Warning
  • Warnings (alias of Warning)
  • Warns
  • Yield (alias of Yields)
  • Yields

Autodoc

See sphinx.ext.autodoc – Include documentation from docstrings.

.. automodule:: my_module
    :members:
    :members: member1, member2
    :undoc-members:
    :private-members:
    :special-members:
    :synopsis: Short description
    :platform: Linux, OS-X, other platform
    :deprecated:
    :show-inheritance:
    :inherited-members:

.. autoclass:: MyClass
.. autoexception:: MyException
    :members:
    :members: member1, member2
    :undoc-members:
    :private-members:
    :special-members:
    :show-inheritance:
    :inherited-members:

.. autofunction:: my_function
.. autofunction:: my_function(arg1, arg2)
.. automethod:: my_method
.. automethod:: my_method(arg1, arg2)

.. autodata::
.. autoattribute::
    :annotation: Short description

Three ways of documenting module data members and class attributes:

#: Single- or multi-line comment before the definition,
#: starting with ``#:``.
foo = "bar"  #: Single line comment *after* the definition.
"""Docstring below the definition."""

Intersphinx

Intersphinx is configured with the following mappings:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3.6/', 'python.inv'),
    'sphinx': ('http://www.sphinx-doc.org/en/stable/', 'sphinx.inv'),
    'aiohttp': ('http://aiohttp.readthedocs.io/en/stable/', 'aiohttp.inv'),
    'aiopg': ('https://aiopg.readthedocs.io/en/stable/', 'aiopg.inv'),
    'jwt': ('https://pyjwt.readthedocs.io/en/latest/', 'jwt.inv'),
}

For each of these external packages, a full list of available reference targets can be found in the corresponding *.inv.txt files in the sphinx/ directory (after the first build).