Documentation

There are two parts of documentation in the Bcfg2 project:

The wiki

A python-based Trac instance is used for the Bcfg2 development website. The Wiki part of the website can be edited after you have successfully logged in. In order to login, a vaild OpenID provider is needed. Please request your access to the Wiki on the Mailing List or in the IRC Channel.

The manual

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.

Building the Manual

  • For Debian (Lenny) the tools are available in the backports repository; installation can be done with the following:

    apt-get -t lenny-backports install python-sphinx

  • 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:

  • LaTeX
  • pdftex

  • Download the source. Please refer to Installation from source for more details.

  • Build the HTML version by running the following command in the top level of the source directory. The output will appear in build/sphinx/html:

    python setup.py build_sphinx

  • Building the PDF version

    python setup.py build_sphinx --builder=latex
cd build/sphinx/latex
make

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 hindrance.

Basics

Bcfg2

When referring to project, Bcfg2 is the preferred use of case.

Monospace fonts

When referring to commands written on the command line use monospace fonts.

Repository

When used alone this refers to a Bcfg2 repository. When there is a chance for confusion, for instance in documents that also discuss VCS, be sure to use the longer phrase “Bcfg2 repository”.

Sections

Unless necessary, all the documentation follows the sections header rules available at http://docs.python.org/devguide/documenting.html#sections