Plugins » Sphinx

Makes it possible to document APIs with the Python doc theme using external files in a way similar to Sphinx.

Download the m/sphinx.py file, put it including the m/ directory into one of your PLUGIN_PATHS and add m.sphinx package to your PLUGINS in pelicanconf.py. The M_SPHINX_INVENTORIES option is described in the Links to external Sphinx documentation section below.

PLUGINS += ['m.sphinx']
M_SPHINX_INVENTORIES = [...]

Python doc theme

List the plugin in your PLUGINS. The M_SPHINX_INVENTORIES configuration option is described in the Links to external Sphinx documentation section below, additionally it supports also the inverse — saving internal symbols to a file to be linked from elsewhere, see Creating an Intersphinx inventory file for a description of the M_SPHINX_INVENTORY_OUTPUT option.

PLUGINS += ['m.sphinx']
M_SPHINX_INVENTORIES = [...]
M_SPHINX_INVENTORY_OUTPUT = 'objects.inv'
M_SPHINX_PARSE_DOCSTRINGS = False

Links to external Sphinx documentation

Sphinx provides a so-called Intersphinx files to make names from one documentation available for linking from elsewhere. The plugin supports the (current) version 2 of those inventory files, version 1 is not supported. You need to provide a list of tuples containing tag file path, URL prefix, an optional list of implicitly prepended name prefixes and an optional list of CSS classes for each link in M_SPHINX_INVENTORIES. Every Sphinx-generated documentation contains an objects.inv file in its root directory (and the root directory is the URL prefix as well), for example for Python 3 it’s located at https://docs.python.org/3/objects.inv. Download the files and specify path to them and the URL they were downloaded from, for example:

M_SPHINX_INVENTORIES = [
    ('sphinx/python.inv', 'https://docs.python.org/3/', ['xml.']),
    ('sphinx/numpy.inv', 'https://docs.scipy.org/doc/numpy/', [], ['m-flat'])]

Use the :ref: interpreted text role for linking to those symbols. Link text is equal to link target unless the target provides its own title (such as documentation pages), function links have () appended to make it clear it’s a function. It’s possible to specify custom link title using the :ref: link title <link-target>“` syntax. If a symbol can’t be found, a warning is printed to output and link target is rendered in a monospace font (or, if custom link title is specified, just the title is rendered, as normal text). You can append #anchor to link-target to link to anchors that are not present in the inventory file, the same works for query parameters starting with ?. Adding custom CSS classes can be done by deriving the role and adding the :class: option.

Shorthand linking and disambiguation

Specifying fully-qualified name for every link would get very boring very fast, which is why the M_SPHINX_INVENTORIES option allows you to specify a list of global implicitly prepended prefixes. Apart from that, the prefixes can be set also on a per-page basis by listing them in :ref-prefix: in page metadata. This is useful especially when writing pages in the Python doc theme to avoid writing the fully qualified name every time you need to linking to some documented name.

Finally, when using the :ref: role in any of the directives described in the Module, class, enum, function, property and data docs section below, path of the currently documented name is used as well. This can save you from repeated typing when for example referencing members of a currently documented class.

The name matching is always done in this order:

as-is, with no prefix, so :ref:`open()` always matches the builtin open() and not whatever else found in current scope
in case of the documentation directives, with increasingly shortened path of currently documented name prepended
prefixes from :ref-prefix:
prefixes from M_SPHINX_INVENTORIES

In order to disambiguate, you have a few options. Specifying larger prefix is usually enough; if you suffix the link target with (), the plugin will restrict the name search to just functions; and finally you can also restrict the search to a particular type by prefixing the target with a concrete target name and a colon — for example, :ref:`std:doc:using/cmdline` will link to the using/cmdline page of standard documentation.

The :ref: a good candidate for a default role — setting it using .. default-role:: will then make it accessible using plain backticks.

.. among page metadata
:ref-prefix:
    typing
    unittest.mock

.. default-role:: ref

.. role:: ref-flat(ref)
    :class: m-flat

-   Function link: :ref:`open()`
-   Class link (with the ``xml.`` prefix omitted): :ref:`etree.ElementTree`
-   Page link: :ref:`std:doc:using/cmdline`
-   :ref:`Custom link title <PyErr_SetString>`
-   Flat link: :ref-flat:`os.path.join()`
-   Omitting :rst:`:ref-prefix:`: :ref:`Tuple`, :ref:`NonCallableMagicMock`
-   Link using a default role: `str.partition()`

Function link: open()
Class link (with the xml. prefix omitted): etree.ElementTree
Page link: Command line and environment
Custom link title
Flat link: os.path.join()
Omitting :ref-prefix:: Tuple, NonCallableMagicMock
Link using a default role: str.partition()

When used with the Python doc theme, the :ref can be used also for linking to internal types, while external types, classes and enums are also linked to from all signatures.

Creating an Intersphinx inventory file

In the Python doc theme, the M_SPHINX_INVENTORY_OUTPUT option can be used to produce an Intersphinx inventory file — basically an inverse of M_SPHINX_INVENTORIES. Set it to a filename and the plugin will fill it with all names present in the documentation. Commonly, Sphinx projects expect this file to be named objects.inv and located in the documentation root, so doing the following will ensure it can be easily used:

M_SPHINX_INVENTORY_OUTPUT = 'objects.inv'

Inventory file format

The format is unfortunately not well-documented in Sphinx itself and this plugin additionally makes some extensions to it, so the following is a description of the file structure as used by m.css. File header is a few textual lines as shown below, while everything after is zlib-compressed. The plugin creates the inventory file in the (current) version 2 and at the moment hardcodes project name to X and version to 0:

# Sphinx inventory version 2
# Project: X
# Version: 0
# The remainder of this file is compressed using zlib.

When decompressing the rest, the contents are again textual, each line being one entry:

mymodule.MyClass py:class 2 mymodule.MyClass.html -
mymodule.foo py:function 2 mymodule.html#foo -
my-page std:doc 2 my-page.html A documentation page

Field	Description
name	Name of the module, class, function, page… Basically the link target used by `:ref:`.
type	Type. Files created by the `m.sphinx` plugins always use only the following types; Sphinx-created files may have arbitrary other types such as `c:function`. This type is what can be used in `:ref:` to further disambiguate the target. `py:module` for modules `py:class` for classes `py:function` m.css-specific for functions, but currently also methods, class methods and static methods. Sphinx uses `py:classmethod`, `py:staticmethod` and `py:method` instead. `py:attribute` for properties `py:enum` m.css-specific for enums. Sphinx treats those the same as `py:class`. `py:enumvalue` m.css-specific for enum values. Sphinx treats those the same as `py:data`. `py:data` for data `std:doc` for pages `std::special` m.css-specific for special pages such as class / module / page listing
`2`	A mysterious number. Sphinx implementation denotes this as `prio` but doesn’t use it in any way.
url	Full url of the page. There’s a minor space-saving optimization — if the URL ends with `$`, it should be composed as `location = location[:-1] + name`. The plugin can recognize this feature but doesn’t make use of it when writing the file.
title	Link title. If set to `-`, `name` should be used as a link title instead.

For debugging purposes, the sphinx.py plugin script can decode and print inventory files passed to it on the command line. See --help for more options.

$ ./m/sphinx.py python.inv
# Sphinx inventory version 2
# Project: Python
# Version: 3.7
# The remainder of this file is compressed using zlib.
CO_FUTURE_DIVISION c:var 1 c-api/veryhigh.html#c.$ -
PYMEM_DOMAIN_MEM c:var 1 c-api/memory.html#c.$ -
PYMEM_DOMAIN_OBJ c:var 1 c-api/memory.html#c.$ -
...

Module, class, enum, function, property and data docs

In the Python doc theme, the .. py:module::, .. py:class::, .. py:enum::, .. py:enumvalue::, .. py:function::, .. py:property:: and .. py:data:: directives provide a way to supply module, class, enum, function / method, property and data documentation content.

Directive option is the name to document, directive contents are the actual contents; in addition all directives except .. py:enumvalue:: have an :summary: option that can override the docstring extracted using inspection. No restrictions are made on the contents, it’s also possible to make use of any additional plugins in the markup. Example:

.. py:module:: mymodule
    :summary: A top-level module.

    This is the top-level module.

    Usage
    -----

    .. code:: pycon

        >>> import mymodule
        >>> mymodule.foo()
        Hello world!

.. py:data:: mymodule.ALMOST_PI
    :summary: :math:`\pi`, but *less precise*.

By default, unlike docstrings, the :summary: is interpreted as reST, which means you can keep the docstring formatting simpler (for display inside IDEs or via the builtin help()), while supplying an alternative and more complex-formatted summary for the actual rendered docs. It’s however possible to enable reST parsing for docstrings as well — see Using parsed docstrings below.

Restrictions

Names described using these directives have to actually exist (i.e., be accessible via inspection) in given module. If a referenced name doesn’t exist, a warning will be printed during processing and its documentation ignored.

Similarly, documentation supplied using these directives cannot override any inspected properties of the names it documents — the type info, function signatures, property mutability or default values can only be specified through code itself. This is a design decision done in order to ensure code and documentation stay in sync as much as possible. If you really need to modify these for documentation purposes, you can do it during the module import in the main configuration file. For example:

import mymodule

# Due to various reasons, foo()'s annotated return type is `object`.
# Change it to `str` for the documentation.
mymodule.foo.__annotations__['return'] = str

INPUT_MODULES = [mymodule]

Modules

The .. py:module:: directive documents a Python module. In addition, the directive supports a :data name: option for convenient documenting of module-level data. The option is equivalent to filling out just a :summary: of the .. py:data:: directive described below.

.. py:module:: math
    :summary: Common mathematical functions
    :data pi:   The value of :math:`\pi`
    :data tau:  The value of :math:`\tau`. Or :math:`2 \pi`.

    This module defines common mathematical functions and constants as
    defined by the C standard.

Classes

Use .. py:class:: for documenting classes. Similarly to module docs, this directive supports an additional :data name: option for documenting class-level data as well as :property name: for properties. Both of those are equivalent to filling out a :summary: of the .. py:data:: / .. py:property:: directives described below.

.. py:class:: mymodule.MyContainer
    :summary: A container of key/value pairs
    :property size: Number of entries in the container

    Provides a key/value storage with :math:`\mathcal{O}(\log{}n)`-complexity
    access.

Enums and enum values

Use .. py:enum:: for documenting enums. Values can be documented either using the .. py:enumvalue:: directive, or in case of short descriptions, conveniently directly in the .. py:enum:: directive via :value name: options. Example:

.. py:enum:: mymodule.MemoryUsage
    :summary: Specifies memory usage configuration
    :value LOW: Optimized for low-memory big-storage devices, such as
        refrigerators.
    :value HIGH: The memory usage will make you angry.

.. py:enumvalue:: mymodule.MemoryUsage.DEFAULT

    Default memory usage. Behavior depends on platform:

    -   On low-memory devices such as refrigerators equivalent to :ref:`LOW`.
    -   On high-end desktop PCs, this is equivalent to :ref:`HIGH`.
    -   On laptops, this randomly chooses between the two values based
        Murphy's law. Enjoy the battery life when you need it the least.

Functions

The .. py:function:: directive supports additional options — :param name: for documenting parameters, :raise name: for documenting raised exceptions and :return: for documenting the return value. It’s allowed to have either none or all parameters documented (the self parameter can be omitted), having them documented only partially or documenting parameters that are not present in the function signature will cause a warning. Documenting one parameter multiple times causes a warning, on the other hand listing one exception multiple times is a valid use case. Example:

.. py:function:: mymodule.MyContainer.add
    :summary: Add a key/value pair to the container
    :param key:                 Key to add
    :param value:               Corresponding value
    :param overwrite_existing:  Overwrite existing value if already present
        in the container
    :raise ValueError:  If the key type is not hashable
    :return:                    The inserted tuple or the existing
        key/value pair in case :p:`overwrite_existing` is not set

    The operation has a :math:`\mathcal{O}(\log{}n)` complexity.

For overloaded functions (such as those coming from pybind11), it’s possible to specify the full signature to distinguish between particular overloads. Directives with the full signature have a priority, if no signature matches given function, a signature-less directive is searched for as a fallback. Example:

.. py:function:: magnum.math.dot(a: magnum.Complex, b: magnum.Complex)
    :summary: Dot product of two complex numbers

.. py:function:: magnum.math.dot(a: magnum.Quaternion, b: magnum.Quaternion)
    :summary: Dot product of two quaternions

.. py:function:: magnum.math.dot
    :summary: Dot product

    .. this documentation will be used for all other overloads

Properties

Use .. py:property:: for documenting properties. This directive supports the :raise name: option similarly as for functions, plus the usual :summary:. For convenience, properties that have just a summary can be also documented directly in the enclosing .. py:class:: directive as shown above.

.. py:property:: mymodule.MyContainer.size
    :summary: Number of entries in the container

    You can also use ``if not container`` for checking if the container is
    empty.

Data

Use .. py:data:: for documenting module-level and class-level data. This directive doesn’t support any additional options besides :summary:. For convenience, data that have just a summary can be also documented directly in the enclosing .. py:module:: / .. py:class:: directive as shown above.

.. py:data:: math.pi
    :summary: The value of :math:`\tau`. Or :math:`2 \pi`.

    They say `pi is wrong <https://tauday.com/>`_.

Using parsed docstrings

By default, docstrings are treated by the Python doc generator as plain text and only externally-supplied docs are parsed. This is done because, for example in Python standard library, embedded docstrings are often very terse without any markup and full docs are external. If you want the docstrings to be parsed, enable the M_SPHINX_PARSE_DOCSTRINGS option. Compared to the directives above, there’s only one difference — instead of a :summary: option, the first paragraph is taken as a summary, the second paragraph as the option list (if it contains option fields) and the rest as documentation content. Continuing with the .. py:function:: example above, embedded in a docstring it would look like this instead:

def add(self, key, value, *, overwrite_existing=False):
    """Add a key/value pair to the container

    :param key:                 Key to add
    :param value:               Corresponding value
    :param overwrite_existing:  Overwrite existing value if already present
        in the container
    :return:                    The inserted tuple or the existing
        key/value pair in case ``overwrite_existing`` is not set

    The operation has a :math:`\mathcal{O}(\log{}n)` complexity.
    """