From 7d277c0d5fef3d0cdb9ca9b97cb2bca09f0f46c5 Mon Sep 17 00:00:00 2001
From: "Chris St. Pierre" <chris.a.st.pierre@gmail.com>
Date: Thu, 6 Sep 2012 13:55:50 -0400
Subject: Documented all plugin helper objects

---
 doc/conf.py                 | 33 ++++++++++++++++++++++++++++++++-
 doc/development/plugins.txt | 33 +++++++++++++++++++++------------
 2 files changed, 53 insertions(+), 13 deletions(-)

(limited to 'doc')

diff --git a/doc/conf.py b/doc/conf.py
index 4497b78d7..cc471e776 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,6 +12,7 @@
 # serve to show the default.
 
 import os
+import re
 import sys
 import time
 
@@ -24,7 +25,8 @@ import time
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
+              'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -212,4 +214,33 @@ else:
 # If false, no module index is generated.
 latex_use_modindex = False
 
+# autodoc settings
 autodoc_default_flags = ['members', 'show-inheritance']
+autoclass_content = "both"
+
+private_re = re.compile(r'^\s*\.\.\s*private-include\s*$')
+
+def skip_member_from_docstring(app, what, name, obj, skip, options):
+    """ since sphinx 1.0 autodoc doesn't support the :private-members:
+    directive, this function allows you to specify
+    ``.. private-include`` in the docstring of a private method, etc.,
+    to ensure that it's included. This only works on things with
+    docstrings """
+    if (not skip or 
+        not hasattr(obj, '__doc__') or not obj.__doc__):
+        return skip
+
+    for line in obj.__doc__.splitlines():
+        if private_re.match(line):
+            return False
+    
+    return skip
+
+def setup(app):
+    app.connect('autodoc-skip-member', skip_member_from_docstring)
+
+# intersphinx settings
+intersphinx_mapping = dict(
+    py=('http://docs.python.org/%s' % '.'.join(str(v)
+                                               for v in sys.version_info[0:2]),
+        None))
diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt
index bb1f0f046..5a1ceb885 100644
--- a/doc/development/plugins.txt
+++ b/doc/development/plugins.txt
@@ -23,30 +23,32 @@ core functionality of Bcfg2 is implemented by several plugins, however,
 they are not special in any way; new plugins could easily supplant one
 or all of them.
 
+.. automodule:: Bcfg2.Server.Plugin
+   :no-members:
+
 Server Plugin Types
 -------------------
 
 A plugin must implement at least one of the interfaces described
 below.  Each interface is available as a class in
-:mod:``Bcfg2.Server.Plugin``.  In most cases, a plugin must also
-inherit from :class:`Bcfg2.Server.Plugin.Plugin`, which is the base
-Plugin object (described below).  Some of the interfaces listed below
-are themselves Plugin objects, so your custom plugin would only need
-to inherit from the plugin type.
+:mod:`Bcfg2.Server.Plugin`.  In most cases, a plugin must also
+inherit from :class:`Bcfg2.Server.Plugin.base.Plugin`, which is the
+base Plugin object (described below).  Some of the interfaces listed
+below are themselves Plugin objects, so your custom plugin would only
+need to inherit from the plugin type.
 
 Plugin
 ^^^^^^
 
-.. autoclass:: Bcfg2.Server.Plugin.Plugin
+.. autoclass:: Bcfg2.Server.Plugin.base.Plugin
    :inherited-members:
    :show-inheritance:
 
-   .. automethod:: Bcfg2.Server.Plugin.Plugin.__init__
-
-With the exceptions of :class:`Bcfg2.Server.Plugin.Statistics` and
-:class:`Bcfg2.Server.Plugin.ThreadedStatistics`, the plugin interfaces
-listed below do **not** inherit from Plugin; they simply provide
-interfaces that a given plugin may or must implement.
+With the exceptions of
+:class:`Bcfg2.Server.Plugin.interfaces.Statistics` and
+:class:`Bcfg2.Server.Plugin.interfaces.ThreadedStatistics`, the plugin
+interfaces listed below do **not** inherit from Plugin; they simply
+provide interfaces that a given plugin may or must implement.
 
 Interfaces
 ^^^^^^^^^^
@@ -96,6 +98,13 @@ Plugin Helper Classes
 ---------------------
 
 .. automodule:: Bcfg2.Server.Plugin.helpers
+   :inherited-members:
+
+.. Debuggable is in base to avoid circular imports, but it's a helper
+.. and should be listed here in the docs
+
+.. autoclass:: Bcfg2.Server.Plugin.base.Debuggable
+   :inherited-members:
 
 Plugin Exceptions
 -----------------
-- 
cgit v1.2.3-1-g7c22