diff options
author | Doug Hellmann <doug@doughellmann.com> | 2015-05-16 13:53:35 -0400 |
---|---|---|
committer | Doug Hellmann <doug@doughellmann.com> | 2015-05-27 23:36:04 +0000 |
commit | 7295f785f055d1551f4d61b7d1d500bac04dfa9f (patch) | |
tree | 8d6cd11dda10c71cb44424aec792eb7bdafe8bfb /doc/source | |
parent | d4e7ad898eb3963480306cd1df36854cc7c6abd5 (diff) | |
download | stevedore-7295f785f055d1551f4d61b7d1d500bac04dfa9f.tar.gz |
Add sphinx integration
Add a restructuredtext directive for documenting a set of plugins with
the needed hooks to make it available is sphinx.
Change-Id: I1a24f9326b4e54174d9dc0ae366315fe29c3ac1b
Diffstat (limited to 'doc/source')
-rw-r--r-- | doc/source/conf.py | 1 | ||||
-rw-r--r-- | doc/source/index.rst | 1 | ||||
-rw-r--r-- | doc/source/sphinxext.rst | 73 |
3 files changed, 75 insertions, 0 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py index 16f953e..c606daa 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -32,6 +32,7 @@ extensions = [ 'sphinx.ext.graphviz', 'sphinx.ext.extlinks', 'oslosphinx', + 'stevedore.sphinxext', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/index.rst b/doc/source/index.rst index 884c014..9fa9548 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -21,6 +21,7 @@ Contents: patterns_enabling tutorial/index managers + sphinxext install essays/* history diff --git a/doc/source/sphinxext.rst b/doc/source/sphinxext.rst new file mode 100644 index 0000000..99f5ea3 --- /dev/null +++ b/doc/source/sphinxext.rst @@ -0,0 +1,73 @@ +==================== + Sphinx Integration +==================== + +Stevedore includes an extension for integrating with Sphinx to +automatically produce documentation about the supported plugins. To +activate the plugin add ``stevedore.sphinxext`` to the list of +extensions in your ``conf.py``. + +.. rst:directive:: .. list-plugins:: namespace + + List the plugins in a namespace. + + Options: + + ``detailed`` + Flag to switch between simple and detailed output (see + below). + ``overline-style`` + Character to use to draw line above header, + defaults to none. + ``underline-style`` + Character to use to draw line below header, + defaults to ``=``. + +Simple List +=========== + +By default, the ``list-plugins`` directive produces a simple list of +plugins in a given namespace including the name and the first line of +the docstring. For example: + +:: + + .. list-plugins:: stevedore.example.formatter + +produces + +------ + +.. list-plugins:: stevedore.example.formatter + +------ + +Detailed Lists +============== + +Adding the ``detailed`` flag to the directive causes the output to +include a separate subsection for each plugin, with the full docstring +rendered. The section heading level can be controlled using the +``underline-style`` and ``overline-style`` options to fit the results +into the structure of your existing document. + +:: + + .. list-plugins:: stevedore.example.formatter + :detailed: + +produces + +------ + +.. list-plugins:: stevedore.example.formatter + :detailed: + :underline-style: - + +------ + +.. note:: + + Depending on how Sphinx is configured, bad reStructuredText syntax in + the docstrings of the plugins may cause the documentation build to + fail completely when detailed mode is enabled. |