/doc/plugins/documenting.rst

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

 1Documenting plugins
 2===================
 3
 4A parable. If a plugin is released on pypi without any documentation, does
 5anyone care?
 6
 7To make it easy to document your plugins, nose includes a `Sphinx`_ extension
 8that will automatically generate plugin docs like those for nose's builtin
 9plugins. Simply add 'nose.sphinx.pluginopts' to the list of extensions in your
10conf.py::
11
12  extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
13                'nose.sphinx.pluginopts']
14
15Then in your plugin documents, include a title and the ``.. autoplugin``
16directive::
17
18  My Cool Plugin
19  ==============
20
21  .. autoplugin :: package.module.with.plugin
22     :plugin: PluginClass
23
24The ``:plugin:`` option is optional. In most cases, the directive will
25automatically detect which class in the named module is the plugin to be
26documented.
27
28The output of the directive includes the docstring of the plugin module, the
29options defined by the plugin, `autodoc`_ generated for the plugin class, and
30the plugin module source. This is roughly equivalent to::
31
32  My Cool Plugin
33  ==============
34
35  .. automodule :: package.module.with.plugin
36
37  Options
38  -------
39  
40  .. cmdoption :: --with-coolness
41
42     Help text of the coolness option.
43
44  .. cmdoption :: 
45
46  Plugin
47  -------
48 
49  .. autoclass :: package.module.with.plugin.PluginClass
50     :members:
51
52  Source
53  ------
54
55  .. include :: path/to/package/module/with/plugin.py
56     :literal:
57
58Document your plugins! Your users might not thank you -- but at least you'll
59*have* some users.
60
61.. _`Sphinx` : http://sphinx.pocoo.org/
62.. _`autodoc`: http://sphinx.pocoo.org/ext/autodoc.html