Merge "Add sphinx integration"

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.