What is this project ?

This project is to collect and improve the documentation for the "buildout" tool in a form suitable for delivery via the website http://www.buildout.org. That documentation is in the form of reStructuredText and relies upon the "sphinx" tool to process it into HTML while automatically producing cross-references, indices and such.

Where are the source documents ?

source/

The Sphinx tool relies upon a "table of contents tree" to organize the various source documents into a comprehensive whole. This tree is specified in a source document with the "toctree::" directive. The topmost or master document, as specified in source/conf.py, is source/index.rst. All source documents must end with the ".rst" filename extension.

Note that all documents under the "source/" tree must appear in some toctree directive and Sphinx will emit a warning at document build time if this is not so.

For the overall site, there are two indices; a general index and a module index. The general index is populated with entries from modules, all index-generating description units, and from index directives. The module index contains one entry per module directive.

Useful ReStructuredText roles

:envvar:`somevar`

  Generates an index entry that links back to the one or more occurrences of this role.

:term:`someword`

  Generates a link from where this role occurs to its definition in the sources/glossary.rst document.

:file:`somefilename`

  Formats the name in a special format suitable to filenames.

:command:`somecommand`

  Formats the commandname in a special format suitable to command names.

:program:`someprogram`

  Formats the programname in a special format suitable to program names.

:pep:`number`

  Generates an external link to the appropriate PEP document.

:rfc:`number`

  Generates an external link to the appropriate RFC document.

Useful ReStructuredText directives

.. sourcecode:: python

   Some python code

.. sourcecode:: none

   non-highlighted code

.. literalinclude::  somefile.py
   :language: python
   :linenos:

How do i configure the conversion process ?

source/

conf.py

Where are the deliverable html documents ?

build/

html/

index.html

How is the html styling controlled?

The CSS stylesheet to be used is "default.css" and it comes from Sphinx, but can be overriden by dropping a file under source/_static/.

Who are the organizers of this project ?

• Jeff Rush
• Baiju M
• Alex Clark