diff options
Diffstat (limited to 'doc/development')
| -rw-r--r-- | doc/development/documentation.txt | 27 | ||||
| -rw-r--r-- | doc/development/lint.txt | 167 |
2 files changed, 185 insertions, 9 deletions
diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt index 2a3cf46d1..4d8a7c9f8 100644 --- a/doc/development/documentation.txt +++ b/doc/development/documentation.txt @@ -8,13 +8,14 @@ There are two parts of documentation in the Bcfg2 project: -* The wiki -* The manual +* The Wiki_ +* The Manual_ The wiki ======== .. _Wiki: http://bcfg2.org +.. _Manual: http://docs.bcfg2.org .. _Trac: http://trac.edgewall.org/ .. _OpenID: https://openid.org/ .. _MCS: http://www.mcs.anl.gov/ @@ -31,9 +32,9 @@ The manual ========== .. _rst: http://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: http://sphinx.pocoo.org -.. _Docutils: +.. _Docutils: http://docutils.sourceforge.net -The source for the manual is located in the ``doc/`` directory in the +The source for the Manual_ is located in the ``doc/`` directory in the git repository or in the source tarball. All files are written in rst_ (ReStructuredText) format. Sphinx_ is used to build the documentation from the restructured text sources. @@ -49,11 +50,20 @@ Building the Manual apt-get -t lenny-backports install python-sphinx - * The needed tools for Fedora based systems are in the `Fedora + * The tools for Fedora based systems are in the `Fedora Package Collection <https://admin.fedoraproject.org/pkgdb>`_; installation can be done easily with Yum:: yum -y install python-sphinx python-docutils + + * The tools for RHEL6-based systems are in the base distribution; you can install them with Yum:: + + yum -y install python-sphinx python-docutils + + * The tools for RHEL5-based systems are in the `Extra Packages for Enterprise Linux(EPEL) <https://fedoraproject.org/wiki/EPEL>`_ repository; if your system is configured for EPEL, you can install them with Yum:: + + yum -y install python-sphinx python-docutils + * Additionally, to build the PDF version: @@ -80,14 +90,14 @@ Documentation Style Guide for Bcfg2 =================================== This is a style guide to use when creating documentation for Bcfg2. It -is meant to be helpful, not a hinderence. +is meant to be helpful, not a hindrance. Basics ------ **Bcfg2** - When referring to project, Bcfg2 is the preferred use of cases. + When referring to project, Bcfg2 is the preferred use of case. **Monospace fonts** @@ -97,8 +107,7 @@ Basics **Repository** When used alone this refers to a Bcfg2 :term:`repository`. When there - is a chance for confusion, for instance in documents also talking - about :term:`VCS`, be sure to use the longer Bcfg2 :term:`repository`. + is a chance for confusion, for instance in documents that also discuss :term:`VCS`, be sure to use the longer phrase "Bcfg2 :term:`repository`". Sections -------- diff --git a/doc/development/lint.txt b/doc/development/lint.txt new file mode 100644 index 000000000..6a4651f92 --- /dev/null +++ b/doc/development/lint.txt @@ -0,0 +1,167 @@ +.. -*- mode: rst -*- + +.. _development-lint: + +=============================== + bcfg2-lint Plugin Development +=============================== + +``bcfg2-lint``, like most parts of Bcfg2, has a pluggable backend that +lets you easily write your own plugins to verify various parts of your +Bcfg2 specification. + +Plugins are loaded in one of two ways: + +* They may be included in a module of the same name as the plugin + class in :mod:`Bcfg2.Server.Lint`, e.g., + :mod:`Bcfg2.Server.Lint.Validate`. +* They may be included directly in a Bcfg2 server plugin, called + "<plugin>Lint", e.g., + :class:`Bcfg2.Server.Plugins.Metadata.MetadataLint`. + +Plugin Types +============ + +There are two types of ``bcfg2-lint`` plugins: + +Serverless plugins +------------------ + +Serverless plugins are run before ``bcfg2-lint`` starts up a local +Bcfg2 server, so the amount of introspection they can do is fairly +limited. They can directly examine the Bcfg2 specification, of +course, but they can't examine the entries handled by a given plugin +or anything that requires a running server. + +If a serverless plugin raises a lint error, however, the server will +not be started and no `Server plugins`_ will be run. This makes them +useful to check for the sorts of errors that might prevent the Bcfg2 +server from starting properly. + +Serverless plugins must subclass +:class:`Bcfg2.Server.Lint.ServerlessPlugin`. + +:mod:`Bcfg2.Server.Lint.Validate` is an example of a serverless +plugin. + +Server plugins +-------------- + +Server plugins are run after a local Bcfg2 server has been started, +and have full access to all of the parsed data and so on. Because of +this, they tend to be easier to use than `Serverless plugins`_, and +thus are more common. + +Server plugins are only run if all `Serverless plugins`_ run +successfully (i.e., raise no errors). + +Server plugins must subclass :class:`Bcfg2.Server.Lint.ServerPlugin`. + +:mod:`Bcfg2.Server.Lint.Genshi` is an example of a server plugin. + +Error Handling +============== + +The job of a ``bcfg2-lint`` plugin is to find errors. Each error that +a plugin may produce must have a name, a short string that briefly +describes the error and will be used to configure error levels in +``bcfg2.conf``. It must also have a default reporting level. +Possible reporting levels are "error", "warning", or "silent". All of +the errors that may be produced by a plugin must be returned as a dict +by :func:`Bcfg2.Server.Lint.Plugin.Errors`. For instance, consider +:func:`Bcfg2.Server.Lint.InfoXML.InfoXML.Errors`: + +.. code-block:: python + + @classmethod + def Errors(cls): + return {"no-infoxml": "warning", + "deprecated-info-file": "warning", + "paranoid-false": "warning", + "required-infoxml-attrs-missing": "error"} + +This means that the :class:`Bcfg2.Server.Lint.InfoXML.InfoXML` lint +plugin can produce five lint errors, although four of them are just +warnings by default. + +The errors returned by each plugin's ``Errors()`` method will be +passed to :func:`Bcfg2.Server.Lint.ErrorHandler.RegisterErrors`, which +will use that information and the information in the config file to +determine how to display (or not display) each error to the end user. + +Errors are produced in a plugin with +:func:`Bcfg2.Server.Lint.Plugin.LintError`, which takes two arguments: +the name of the error, which must correspond to a key in the dict +returned by :func:`Bcfg2.Server.Lint.Plugin.Errors`, and a freeform +string that will be displayed to the end user. Note that the error +name and its display are thus only tied together when the error is +produced; that is, a single error (by name) can have two completely +different outputs. + +Basics +====== + +.. automodule:: Bcfg2.Server.Lint + +Existing ``bcfg2-lint`` Plugins +=============================== + +BundlerLint +----------- + +.. autoclass:: Bcfg2.Server.Plugins.Bundler.BundlerLint + +Comments +-------- + +.. automodule:: Bcfg2.Server.Lint.Comments + +Genshi +------ + +.. automodule:: Bcfg2.Server.Lint.Genshi + +GroupNames +---------- + +.. automodule:: Bcfg2.Server.Lint.GroupNames + +GroupPatternsLint +----------------- + +.. autoclass:: Bcfg2.Server.Plugins.GroupPatterns.GroupPatternsLint + +InfoXML +------- + +.. automodule:: Bcfg2.Server.Lint.InfoXML + +MergeFiles +---------- + +.. automodule:: Bcfg2.Server.Lint.MergeFiles + +MetadataLint +------------ + +.. autoclass:: Bcfg2.Server.Plugins.Metadata.MetadataLint + +PkgmgrLint +---------- + +.. autoclass:: Bcfg2.Server.Plugins.Pkgmgr.PkgmgrLint + +RequiredAttrs +------------- + +.. automodule:: Bcfg2.Server.Lint.RequiredAttrs + +TemplateHelperLint +------------------ + +.. autoclass:: Bcfg2.Server.Plugins.TemplateHelper.TemplateHelperLint + +Validate +-------- + +.. automodule:: Bcfg2.Server.Lint.Validate |