From 48069b7ac4e514ce21680fe209dd40224322346c Mon Sep 17 00:00:00 2001 From: Duncan Hutty Date: Thu, 25 Apr 2013 11:20:14 -0400 Subject: meta docs: about redhat based systems, links, clarity, spelling --- doc/development/documentation.txt | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) (limited to 'doc') 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 `_; 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) `_ 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 -------- -- cgit v1.2.3-1-g7c22 From 139e8abff3eba4a1c6ce1a33f9835b42463583f9 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Mon, 29 Apr 2013 07:24:31 -0500 Subject: doc: Add link to 1.3 stable documentation Signed-off-by: Sol Jerome --- doc/_templates/indexsidebar.html | 1 + 1 file changed, 1 insertion(+) (limited to 'doc') diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 39916315d..2133cdcc5 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -7,5 +7,6 @@ -- cgit v1.2.3-1-g7c22 From 4cb722d650a7cc5d0f58141d309896b901d19784 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 7 May 2013 14:28:22 -0400 Subject: POSIXUsers: allow better syntax --- doc/server/plugins/generators/rules.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/rules.txt b/doc/server/plugins/generators/rules.txt index 845006115..2493be53f 100644 --- a/doc/server/plugins/generators/rules.txt +++ b/doc/server/plugins/generators/rules.txt @@ -395,9 +395,9 @@ For example: - lp - adm - bin + + + x86_64 - - - centos-5.4 - http://mrepo/centos5-x86_64/RPMS.updates + + x86_64 - - - centos-5.4 - http://mrepo/centos5-x86_64/RPMS.extras + + x86_64 - + Due to the :ref:`server-plugins-generators-packages-magic-groups`, -- cgit v1.2.3-1-g7c22 From f262e9274102a64e6d777b4c094bee711b49e314 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Thu, 9 May 2013 13:16:04 -0400 Subject: docs: clarified GroupPatterns docs, fixed typos --- doc/server/plugins/grouping/grouppatterns.txt | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/grouping/grouppatterns.txt b/doc/server/plugins/grouping/grouppatterns.txt index 39c632f82..44ffa5066 100644 --- a/doc/server/plugins/grouping/grouppatterns.txt +++ b/doc/server/plugins/grouping/grouppatterns.txt @@ -8,7 +8,7 @@ GroupPatterns The GroupPatterns plugin is a connector that can assign clients group membership pased on patterns in client hostnames. Two basic -methods are supported: +methods are supported: - regular expressions (NamePatterns) - ranges (NameRange) @@ -20,7 +20,7 @@ Setup ===== #. Enable the GroupPatterns plugin -#. Create the GroupPatterns/config.xml file (similar to the example below). +#. Create the ``GroupPatterns/config.xml`` file (similar to the example below). #. Client groups will be augmented based on the specification Pattern Types @@ -52,7 +52,7 @@ Examples (.*) - group-$1' + group-$1 node[[1-32]] @@ -82,15 +82,14 @@ GroupPatterns configuration: - ^x(\w[^\d|\.]+)\d*\..* + x(\w[^\d\.]+)\d*\. $1-server Regex explanation: -#. !^x Match any hostname that begins with "x" -#. (\w[!^\d|\.]+) followed by one or more word characters that are not a decimal digit or "." and save the string to $1 -#. \d* followed by 0 or more decimal digit(s) -#. \..* followed by a "." -#. .* followed by 1 or more of anything else. +#. ``x`` Match any hostname that begins with "x" +#. ``(\w[!^\d|\.]+)`` followed by one or more word characters that are not a decimal digit or "." and save the string to $1 +#. ``\d*`` followed by 0 or more decimal digit(s) +#. ``\.`` followed by a literal "." -- cgit v1.2.3-1-g7c22 From e55b0dc3b96cdac318dcf07309d18e763ccb7229 Mon Sep 17 00:00:00 2001 From: Sol Jerome Date: Fri, 10 May 2013 12:28:58 -0500 Subject: APT: Allow specification of deb-src lines (Resolves #1148) Signed-off-by: Sol Jerome --- doc/server/plugins/generators/packages.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/generators/packages.txt b/doc/server/plugins/generators/packages.txt index 606e1e128..cdc4f7282 100644 --- a/doc/server/plugins/generators/packages.txt +++ b/doc/server/plugins/generators/packages.txt @@ -252,7 +252,8 @@ something like this: + version="intrepid" + debsrc="true"> main universe i386 @@ -280,7 +281,7 @@ something like this: .. warning:: You must regenerate the Packages cache when adding or removing the recommended attribute (``bcfg2-admin xcmd - Packages.Refresh``). + Packages.Refresh``). .. [#f1] Bcfg2 will by default add **Essential** packages to the client specification. You can disable this behavior by -- cgit v1.2.3-1-g7c22 From 34aff9f18f7a8ee59e8e07ceaf89d79bd6e96509 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 14 May 2013 11:43:14 -0400 Subject: doc: added devel docs for bcfg2-lint plugins --- doc/development/lint.txt | 167 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 doc/development/lint.txt (limited to 'doc') 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 + "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 -- cgit v1.2.3-1-g7c22 From 26168362e761fc81273a4a7a4878b2df36273893 Mon Sep 17 00:00:00 2001 From: "Chris St. Pierre" Date: Tue, 14 May 2013 11:43:28 -0400 Subject: doc: fixed doc warnings --- doc/server/plugins/connectors/grouplogic.txt | 4 ++-- doc/server/plugins/grouping/metadata.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/server/plugins/connectors/grouplogic.txt b/doc/server/plugins/connectors/grouplogic.txt index b9a5b00d6..abf425202 100644 --- a/doc/server/plugins/connectors/grouplogic.txt +++ b/doc/server/plugins/connectors/grouplogic.txt @@ -110,8 +110,8 @@ individually, there's a more elegant way to accomplish the same thing: diff --git a/doc/server/plugins/grouping/metadata.txt b/doc/server/plugins/grouping/metadata.txt index 32834b458..ceac5dc24 100644 --- a/doc/server/plugins/grouping/metadata.txt +++ b/doc/server/plugins/grouping/metadata.txt @@ -222,7 +222,7 @@ to include a different file, or explicit content in the case that the parent include does not exist.) Wildcard XInclude -~~~~~~~~~~~~~~~~~ +----------------- .. versionadded:: 1.3.1 -- cgit v1.2.3-1-g7c22