Documenting plugins — nose 1.3.7 documentation

# Documenting plugins

A parable. If a plugin is released on pypi without any documentation, does anyone care?

To make it easy to document your plugins, nose includes a Sphinx extension that will automatically generate plugin docs like those for nose’s builtin plugins. Simply add ‘nose.sphinx.pluginopts’ to the list of extensions in your conf.py:

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
                  'nose.sphinx.pluginopts']

Then in your plugin documents, include a title and the `.. autoplugin` directive:

    My Cool Plugin
    ==============

    .. autoplugin :: package.module.with.plugin
       :plugin: PluginClass

The `:plugin:` option is optional. In most cases, the directive will automatically detect which class in the named module is the plugin to be documented.

The output of the directive includes the docstring of the plugin module, the options defined by the plugin, autodoc generated for the plugin class, and the plugin module source. This is roughly equivalent to:

    My Cool Plugin
    ==============

    .. automodule :: package.module.with.plugin

    Options
    -------

    .. cmdoption :: --with-coolness

       Help text of the coolness option.

    .. cmdoption ::

    Plugin
    -------

    .. autoclass :: package.module.with.plugin.PluginClass
       :members:

    Source
    ------

    .. include :: path/to/package/module/with/plugin.py
       :literal:

Document your plugins! Your users might not thank you – but at least you’ll have some users.