Plugins » Sphinx

Makes it pos­si­ble to doc­u­ment APIs with the Python doc theme us­ing ex­ter­nal files in a way sim­i­lar to Sphinx.

How to use

Pel­i­can

Down­load the m/sphinx.py file, put it in­clud­ing the m/ di­rec­to­ry in­to one of your PLUGIN_PATHS and add m.sphinx pack­age to your PLUGINS in pelicanconf.py. The M_SPHINX_INVENTORIES op­tion is de­scribed in the Links to ex­ter­nal Sphinx doc­u­men­ta­tion sec­tion be­low.

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

Python doc theme

List the plug­in in your PLUGINS. The M_SPHINX_INVENTORIES con­fig­u­ra­tion op­tion is de­scribed in the Links to ex­ter­nal Sphinx doc­u­men­ta­tion sec­tion be­low, ad­di­tion­al­ly it sup­ports al­so the in­verse — sav­ing in­ter­nal sym­bols to a file to be linked from else­where, see Cre­at­ing an In­ter­sphinx in­ven­to­ry file for a de­scrip­tion of the M_SPHINX_INVENTORY_OUTPUT op­tion.

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

Cre­at­ing an In­ter­sphinx in­ven­to­ry file

In the Python doc theme, the M_SPHINX_INVENTORY_OUTPUT op­tion can be used to pro­duce an In­ter­sphinx in­ven­to­ry file — ba­si­cal­ly an in­verse of M_SPHINX_INVENTORIES. Set it to a file­name and the plug­in will fill it with all names present in the doc­u­men­ta­tion. Com­mon­ly, Sphinx projects ex­pect this file to be named objects.inv and lo­cat­ed in the doc­u­men­ta­tion root, so do­ing the fol­low­ing will en­sure it can be eas­i­ly used:

M_SPHINX_INVENTORY_OUTPUT = 'objects.inv'

Mod­ule, class, enum, func­tion, prop­er­ty and da­ta docs

In the Python doc theme, the .. py:module::, .. py:class::, .. py:enum::, .. py:enumvalue::, .. py:function::, .. py:property:: and .. py:data:: di­rec­tives pro­vide a way to sup­ply mod­ule, class, enum, func­tion / method, prop­er­ty and da­ta doc­u­men­ta­tion con­tent.

Di­rec­tive op­tion is the name to doc­u­ment, di­rec­tive con­tents are the ac­tu­al con­tents; in ad­di­tion all di­rec­tives ex­cept .. py:enumvalue:: have an :summary: op­tion that can over­ride the doc­string ex­tract­ed us­ing in­spec­tion. No re­stric­tions are made on the con­tents, it’s al­so pos­si­ble to make use of any ad­di­tion­al plug­ins in the markup. Ex­am­ple:

.. 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 de­fault, un­like doc­strings, the :summary: is in­ter­pret­ed as reST, which means you can keep the doc­string for­mat­ting sim­pler (for dis­play in­side IDEs or via the builtin help()), while sup­ply­ing an al­ter­na­tive and more com­plex-for­mat­ted sum­ma­ry for the ac­tu­al ren­dered docs. It’s how­ev­er pos­si­ble to en­able reST pars­ing for doc­strings as well — see Us­ing parsed doc­strings be­low.

Mod­ules

The .. py:module:: di­rec­tive doc­u­ments a Python mod­ule. In ad­di­tion, the di­rec­tive sup­ports a :data <name>: op­tion for con­ve­nient doc­u­ment­ing of mod­ule-lev­el da­ta. The op­tion is equiv­a­lent to fill­ing out just a :summary: of the .. py:data:: di­rec­tive de­scribed be­low.

.. 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.

Class­es

Use .. py:class:: for doc­u­ment­ing class­es. Sim­i­lar­ly to mod­ule docs, this di­rec­tive sup­ports an ad­di­tion­al :data <name>: op­tion for doc­u­ment­ing class-lev­el da­ta as well as :property <name>: for prop­er­ties. Both of those are equiv­a­lent to fill­ing out a :summary: of the .. py:data:: / .. py:property:: di­rec­tives de­scribed be­low.

.. 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 val­ues

Use .. py:enum:: for doc­u­ment­ing enums. Val­ues can be doc­u­ment­ed ei­ther us­ing the .. py:enumvalue:: di­rec­tive, or in case of short de­scrip­tions, con­ve­nient­ly di­rect­ly in the .. py:enum:: di­rec­tive via :value <name>: op­tions. Ex­am­ple:

.. 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.

Func­tions

The .. py:function:: di­rec­tive sup­ports ad­di­tion­al op­tions — :param <name>: for doc­u­ment­ing pa­ram­e­ters and :return: for doc­u­ment­ing the re­turn val­ue. It’s al­lowed to have ei­ther none or all pa­ram­e­ters doc­u­ment­ed (the self pa­ram­e­ter can be omit­ted), hav­ing them doc­u­ment­ed on­ly par­tial­ly or doc­u­ment­ing pa­ram­e­ters that are not present in the func­tion sig­na­ture will cause a warn­ing. Ex­am­ple:

.. 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
    :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 over­load­ed func­tions (such as those com­ing from py­bind11), it’s pos­si­ble to spec­i­fy the full sig­na­ture to dis­tin­guish be­tween par­tic­u­lar over­loads. Di­rec­tives with the full sig­na­ture have a pri­or­i­ty, if no sig­na­ture match­es giv­en func­tion, a sig­na­ture-less di­rec­tive is searched for as a fall­back. Ex­am­ple:

.. 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

Prop­er­ties

Use .. py:property:: for doc­u­ment­ing prop­er­ties. This di­rec­tive doesn’t sup­port any ad­di­tion­al op­tions be­sides :summary:. For con­ve­nience, prop­er­ties that have just a sum­ma­ry can be al­so doc­u­ment­ed di­rect­ly in the en­clos­ing .. py:class:: di­rec­tive 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.

Da­ta

Use .. py:data:: for doc­u­ment­ing mod­ule-lev­el and class-lev­el da­ta. This di­rec­tive doesn’t sup­port any ad­di­tion­al op­tions be­sides :summary:. For con­ve­nience, da­ta that have just a sum­ma­ry can be al­so doc­u­ment­ed di­rect­ly in the en­clos­ing .. py:module:: / .. py:class:: di­rec­tive 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/>`_.

Us­ing parsed doc­strings

By de­fault, doc­strings are treat­ed by the Python doc gen­er­a­tor as plain text and on­ly ex­ter­nal­ly-sup­plied docs are parsed. This is done be­cause, for ex­am­ple in Python stan­dard li­brary, em­bed­ded doc­strings are of­ten very terse with­out any markup and full docs are ex­ter­nal. If you want the doc­strings to be parsed, en­able the M_SPHIMX_PARSE_DOCSTRINGS op­tion. Com­pared to the di­rec­tives above, there’s on­ly one dif­fer­ence — in­stead of a :summary: op­tion, the first para­graph is tak­en as a sum­ma­ry, the sec­ond para­graph as the op­tion list (if it con­tains op­tion fields) and the rest as doc­u­men­ta­tion con­tent. Con­tin­u­ing with the .. py:function:: ex­am­ple above, em­bed­ded in a doc­string it would look like this in­stead:

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.
    """