summaryrefslogtreecommitdiffstats
path: root/doc/development
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development')
-rw-r--r--doc/development/docstyleguide.txt33
-rw-r--r--doc/development/documentation.txt51
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.