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

List the plug­in in your PLUGINS.

PLUGINS += ['m.sphinx']

Mod­ule, class and da­ta docs

The .. py:module::, .. py:class:: and .. py:data:: di­rec­tives pro­vide a way to sup­ply mod­ule, class 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 the :summary: op­tion 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 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*.

Com­pared to 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.