*********************
About these documents
*********************

These documents are generated from `reStructuredText
<http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, an excellent
document processor specifically written for the Python documentation
by Georg Brandl and contributors.

Development of this documentation is organized by Uli Fouquet (``uli
at gnufix dot de``). We're always looking for volunteers wanting to
help with the docs, so feel free to send a mail there!

Many thanks go to:

* the `docutils <http://docutils.sf.net/>`_ project for creating
  reStructuredText and the docutils suite;
* Georg Brandl for his `sphinx` package.

See :ref:`reporting-bugs` for information how to report bugs in Python itself.

The `ulif.openoffice` documentation toolchain
=============================================

Grok now makes use of the ``sphinx`` package, which was written by
Georg Brandl and volunteers, to generate the official Python
documentation. Sphinx is able to generate HTML as well as LaTeX and
HTMLHelp formats. The latter is currently not supported by
`ulif.openoffice`.

How can I generate nice HTML/LaTeX/PDF documentation for `ulif.openoffice`?
---------------------------------------------------------------------------


If you have run ``bin/buildout``, than you're nearly finished. This
will generate some scripts in the ``bin/`` directory. Just run::

  $ bin/sphinx-build doc/source doc/build/html

to generate the HTML documentation. The docs will be placed in

  doc/build/html/

For LaTeX/PDF docs you must have LaTeX and ``pdflatex`` installed. If
you want PDF docs, you have to perform two steps.

1) Run::

      $ bin/sphinx-build -b latex doc/source doc/build/latex

   which will generate .tex files and appropriate Makefiles in
   ``doc/build/latex``.

2) Then change to ``doc/buid/latex`` and do::

   $ make

The latter will run `pdflatex` to generate the PDF documents.

Any warnings during the document processing can be ignored for the
time being.

You can run each of the scripts with the `-h` option to see other
available options.

How to tweak the layout/settings of the documentation toolchain
---------------------------------------------------------------

The general settings of documentation generated by ``sphinx`` and
`ulif.openoffice` are settable in a file ``conf.py`` which must be in
the source root directory of your docs. Have a look at
``doc/source/conf.py`` for deeper insights.