diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/conf.py | 40 | ||||
-rw-r--r-- | doc/development/cfg.txt | 100 | ||||
-rw-r--r-- | doc/development/packages.txt | 52 | ||||
-rw-r--r-- | doc/development/plugins.txt | 14 | ||||
-rw-r--r-- | doc/server/plugins/generators/packages.txt | 49 |
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 |