*********************
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 the
package itself.

The `ulif.pynotify` documentation toolchain
=============================================

ulif.pynotify 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.pynotify`.

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


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 docs/_build/html

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

  docs/_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 docs docs/_build/latex

   which will generate .tex files and appropriate Makefiles in
   ``docs/_build/latex``.

2) Then change to ``docs/_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.pynotify` are settable in a file ``conf.py`` which must be in
the source root directory of your docs. Have a look at
``docs/conf.py`` for deeper insights.
