diff options
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/docstyleguide.txt | 33 | ||||
-rw-r--r-- | doc/development/documentation.txt | 51 |
2 files changed, 44 insertions, 40 deletions
diff --git a/doc/development/docstyleguide.txt b/doc/development/docstyleguide.txt deleted file mode 100644 index 59db58362..000000000 --- a/doc/development/docstyleguide.txt +++ /dev/null @@ -1,33 +0,0 @@ -.. -*- mode: rst -*- - -.. _doc-styleguide: - -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. - -Basics ------- - -**Bcfg2** - - When referring to project, Bcfg2 is the preferred use of cases. - -**Monospace fonts** - - When referring to commands written on the command line use monospace - fonts. - -**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`. - -Sections --------- - -Unless necessary, all the documentation follows the sections header -rules available at http://docs.python.org/documenting/rest.html#sections. diff --git a/doc/development/documentation.txt b/doc/development/documentation.txt index 957ca37bd..1e7667cc5 100644 --- a/doc/development/documentation.txt +++ b/doc/development/documentation.txt @@ -2,8 +2,9 @@ .. _development-documentation: -Documentation -============= +=============== + Documentation +=============== There are two parts of documentation in the Bcfg2 project: @@ -12,7 +13,7 @@ There are two parts of documentation in the Bcfg2 project: The wiki --------- +======== .. _Wiki: http://bcfg2.org .. _Trac: http://trac.edgewall.org/ .. _OpenID: https://openid.org/ @@ -27,7 +28,7 @@ provider is needed. Please request your access to the Wiki_ on the The manual ----------- +========== .. _rst: http://en.wikipedia.org/wiki/ReStructuredText .. _Sphinx: http://sphinx.pocoo.org .. _Docutils: @@ -38,15 +39,19 @@ rst_ (ReStructuredText) format. Sphinx_ is used to build the documentation from the restructured text sources. Building the Manual -^^^^^^^^^^^^^^^^^^^ +------------------- * Install the prerequisites. Docutils_ and Sphinx_ are needed to build. - * For Debian (Lenny) the tools are available in the `backports <http://www.backports.org/dokuwiki/doku.php?id=instructionst>`_ repository; installation can be done with the following:: + * For Debian (Lenny) the tools are available in the `backports + <http://www.backports.org/dokuwiki/doku.php?id=instructionst>`_ + repository; installation can be done with the following:: apt-get -t lenny-backports install python-sphinx - * The needed tools for Fedora based systems are in the `Fedora Package Collection <https://admin.fedoraproject.org/pkgdb>`_; installation can be done easily with Yum:: + * The needed 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 @@ -68,3 +73,35 @@ Building the Manual python setup.py build_sphinx --builder=latex cd build/sphinx/latex make + +.. _doc-styleguide: + +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. + +Basics +------ + +**Bcfg2** + + When referring to project, Bcfg2 is the preferred use of cases. + +**Monospace fonts** + + When referring to commands written on the command line use + ``monospace`` fonts. + +**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`. + +Sections +-------- + +Unless necessary, all the documentation follows the sections header +rules available at http://docs.python.org/documenting/rest.html#sections. |