You should do it. Nobody will use your plugins if you don’t. Or if they do use them, they will curse you whenever things go wrong.
One easy way to document your plugins is to use nose2’s Sphinx
extension, which provides an
autoplugin directive that will
produce decent reference documentation from your plugin classes.
To use it, add
nose2.sphinxext to the
extensions list in the
conf.py file in your docs directory.
Then add an
autoplugin directive to a
*.rst file, like this:
.. autoplugin :: mypackage.plugins.PluginClass
This will produce output that includes the config vars your plugin
__init__, as well as any command line options your plugin
registers. This is why you really should extract config vars and
register command-line options in
The output will also include an
autoclass section for your plugin
class, so you can put more narrative documentation in the plugin’s
docstring for users to read.
Of course you can, and should, write some words before the reference
docs explaining what your plugin does and how to use it. You can put
those words in the
*.rst file itself, or in the docstring of the module
where your plugin lives.