Cfg: documented all Cfg modules, added development docs

5 files changed, 193 insertions, 62 deletions

diff --git a/doc/conf.py b/doc/conf.py
index c10c073c3..31a7960fe 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -219,23 +219,37 @@ latex_use_modindex = False
 autodoc_default_flags = ['members', 'show-inheritance']
 autoclass_content = "both"
 
-private_re = re.compile(r'^\s*\.\.\s*private-include\s*$')
+private_re = re.compile(r'^\s*\.\.\s*private-include:\s*(.+)$')
+
+private_include = []
 
 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
+    ``.. private-include: <name>[,<name,...]`` in the docstring of a
+    class containing a private method, etc., to ensure that it's
+    included. Due to a bug in Sphinx, this doesn't work for attributes
+    -- only things that actually have docstrings.  If you want to
+    include private attributes, you have to explicitly include them,
+    either with :members:, or by putting :autoattribute: in the
+    __init__ docstring for a class or module docstring."""
+    global private_include
+    if name == '__doc__':
+        private_include = []
+        if not obj:
+            return None
+        for line in obj.splitlines():
+            match = private_re.match(line)
+            if match:
+                private_include.extend(re.split(r',\s*', match.group(1)))
+        return None
+        
+    if not skip:
+        return None
+
+    if name in private_include:
+        return False
+    return None
 
 def setup(app):
     app.connect('autodoc-skip-member', skip_member_from_docstring)
diff --git a/doc/development/cfg.txt b/doc/development/cfg.txt
new file mode 100644
index 000000000..7d27efb12
--- /dev/null
+++ b/doc/development/cfg.txt
@@ -0,0 +1,100 @@
+.. -*- mode: rst -*-
+
+.. _development-cfg:
+
+=========================
+ Cfg Handler Development
+=========================
+
+The :ref:`server-plugins-generators-cfg` plugin offers multiple
+handlers to handle different entries in different ways.  Writing a new
+Cfg handler is a relatively simple way to add significant new features
+to Cfg.
+
+Each new Cfg handler must be contained in its own module in
+``Bcfg2.Server.Plugins.Cfg``, and the module and class name must be
+identical.  The name should start with ``Cfg``, and should clearly
+indicate which of the handler types it is.  A handler class may
+implement more than one handler type.a
+
+Cfg Handler Types
+=================
+
+There are four different types of Cfg handlers.  A new handler must
+inherit either from one of these classes, or from an existing handler.
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgFilter
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgInfo
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgVerifier
+
+Cfg Handler Base Class
+======================
+
+In addition to the interfaces defined above, all Cfg handlers inherit
+from CfgBaseFileMatcher.
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgBaseFileMatcher
+
+
+Cfg Exceptions
+==============
+
+Cfg handlers may produce the following exceptions:
+
+.. autoexception:: Bcfg2.Server.Plugins.Cfg.CfgVerificationError
+
+In addition, Cfg handlers may produce the following base plugin
+exceptions:
+
+.. autoexception:: Bcfg2.Server.Plugin.exceptions.PluginExecutionError
+   :noindex:
+
+.. autoexception:: Bcfg2.Server.Plugin.exceptions.PluginInitError
+   :noindex:
+
+Accessing Configuration Options
+===============================
+
+.. autoattribute:: Bcfg2.Server.Plugins.Cfg.SETUP
+
+Existing Cfg Handlers
+=====================
+
+Generators
+----------
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgPlaintextGenerator.CfgPlaintextGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgGenshiGenerator.CfgGenshiGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgCheetahGenerator.CfgCheetahGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenerator.CfgEncryptedGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedGenshiGenerator.CfgEncryptedGenshiGenerator
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEncryptedCheetahGenerator.CfgEncryptedCheetahGenerator
+
+Filters
+-------
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgCatFilter.CfgCatFilter
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgDiffFilter.CfgDiffFilter
+
+Info Handlers
+-------------
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgDefaultInfo
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgInfoXML.CfgInfoXML
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgLegacyInfo.CfgLegacyInfo
+
+Verifiers
+---------
+
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgExternalCommandVerifier.CfgExternalCommandVerifier
+
+Other Cfg Objects
+=================
+
+These other objects comprise the remainder of the Cfg plugin, and are
+included for completeness.
+
+.. autoattribute:: Bcfg2.Server.Plugins.Cfg.DEFAULT_INFO
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.CfgEntrySet
+.. autoclass:: Bcfg2.Server.Plugins.Cfg.Cfg
diff --git a/doc/development/packages.txt b/doc/development/packages.txt
new file mode 100644
index 000000000..f85bced38
--- /dev/null
+++ b/doc/development/packages.txt
@@ -0,0 +1,52 @@
+Developing for Packages
+=======================
+
+.. note::
+   
+   This data is old and incomplete, and needs badly to be rewritten.
+
+In order to support a given client package tool driver, that driver
+must support use of the auto value for the version attribute in Package
+entries. In this case, the tool driver views the current state of
+available packages, and uses the underlying package manager's choice of
+correct package version in lieu of an explicit, centrally-specified,
+version. This support enables Packages to provide a list of Package
+entries with version='auto'. Currently, the APT and YUMng drivers support
+this feature. Note that package management systems without any network
+support cannot operate in this fashion, so RPMng and SYSV will never be
+able to use Packages. Emerge, Zypper, IPS, and Blastwave all have the
+needed features to be supported by Packages, but support has not yet
+been written.
+
+Packages fills two major functions in configuration generation. The first
+is to provide entry level binding support for Package entries included
+in client configurations. This function is quite easy to implement;
+Packages determines (based on client group membership) if the package
+is available for the client system, and which type it has. Because
+version='auto' is used, no version determination needs to be done.
+
+The second major function is more complex. Packages ensures that client
+configurations include all package-level prerequisites for package entries
+explicitly included in the configuration. In order to support this,
+Packages needs to directly process network data for package management
+systems (the network sources for apt or yum, for examples), process
+these files, and build data structures describing prerequisites and the
+providers of those functions/paths. To simplify implementations of this,
+there is a generic base class (Bcfg2.Server.Plugins.Packages.Source)
+that provides a framework for fetching network data via HTTP, processing
+those sources (with subclass defined methods for processing the specific
+format provided by the tool), a generic dependency resolution method,
+and a caching mechanism that greatly speeds up server/bcfg2-info startup.
+
+Each source type must define:
+
+* a get_urls attribute (and associated urls property) that describes
+  the URLS where to get data from.
+* a read_files method that reads and processes the downloaded files
+
+Sources may define a get_provides method, if provides are complex. For
+example, provides in rpm can be either rpm names or file paths, so
+multiple data sources need to be multiplexed.
+
+The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a
+relatively simple implementation of a source.
diff --git a/doc/development/plugins.txt b/doc/development/plugins.txt
index 59582e255..183126053 100644
--- a/doc/development/plugins.txt
+++ b/doc/development/plugins.txt
@@ -11,6 +11,18 @@ to implement configuration interfaces and representation tailored to
 problems encountered by a particular site. This chapter describes what
 plugins are good for, what they can do, and how to implement them.
 
+Several plugins themselves have pluggable backends, and for narrow
+cases you may want to develop a backend for an existing plugin rather
+than an entirely new plugin.  See the following pages for more
+information:
+
+.. toctree::
+   :maxdepth: 1
+
+   cfg
+   packages
+
+
 Bcfg2 Plugins
 -------------
 
@@ -41,6 +53,8 @@ Plugin
 ^^^^^^
 
 .. autoclass:: Bcfg2.Server.Plugin.base.Plugin
+   :members: name, __author__, experimental, deprecated, conflicts,
+             sort_order, __rmi__, init_repo, shutdown
    :inherited-members:
    :show-inheritance:
 
diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt
index db463c45a..d2c425f1d 100644
--- a/doc/server/plugins/generators/packages.txt
+++ b/doc/server/plugins/generators/packages.txt
@@ -656,55 +656,6 @@ TODO list
 * Portage support
 * Explicit version pinning (a la Pkgmgr)
 
-Developing for Packages
-=======================
-
-In order to support a given client package tool driver, that driver
-must support use of the auto value for the version attribute in Package
-entries. In this case, the tool driver views the current state of
-available packages, and uses the underlying package manager's choice of
-correct package version in lieu of an explicit, centrally-specified,
-version. This support enables Packages to provide a list of Package
-entries with version='auto'. Currently, the APT and YUMng drivers support
-this feature. Note that package management systems without any network
-support cannot operate in this fashion, so RPMng and SYSV will never be
-able to use Packages. Emerge, Zypper, IPS, and Blastwave all have the
-needed features to be supported by Packages, but support has not yet
-been written.
-
-Packages fills two major functions in configuration generation. The first
-is to provide entry level binding support for Package entries included
-in client configurations. This function is quite easy to implement;
-Packages determines (based on client group membership) if the package
-is available for the client system, and which type it has. Because
-version='auto' is used, no version determination needs to be done.
-
-The second major function is more complex. Packages ensures that client
-configurations include all package-level prerequisites for package entries
-explicitly included in the configuration. In order to support this,
-Packages needs to directly process network data for package management
-systems (the network sources for apt or yum, for examples), process
-these files, and build data structures describing prerequisites and the
-providers of those functions/paths. To simplify implementations of this,
-there is a generic base class (Bcfg2.Server.Plugins.Packages.Source)
-that provides a framework for fetching network data via HTTP, processing
-those sources (with subclass defined methods for processing the specific
-format provided by the tool), a generic dependency resolution method,
-and a caching mechanism that greatly speeds up server/bcfg2-info startup.
-
-Each source type must define:
-
-* a get_urls attribute (and associated urls property) that describes
-  the URLS where to get data from.
-* a read_files method that reads and processes the downloaded files
-
-Sources may define a get_provides method, if provides are complex. For
-example, provides in rpm can be either rpm names or file paths, so
-multiple data sources need to be multiplexed.
-
-The APT source in ``src/lib/Server/Plugins/Packages.py`` provides a
-relatively simple implementation of a source.
-
 .. _configuration:
 
 Configuration