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

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

Development of this documentation and its toolchain takes place on the
grok-dev@zope.org mailing list.  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 Grok
itself.

.. including the ACKS file here so that it can be maintained separately
.. include:: ACKS.txt

It is only with the input and contributions of the Grok community
that Grok has so much documentation -- Thank You!


The Grok 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
other formats.


How can I generate nice HTML/LaTeX/PDF documentation for Grok?
--------------------------------------------------------------

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

  $ bin/grokdocs2html

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. Then, to generate PDF docs, run::

  $ bin/grokdocs2pdf

which will first generate .tex files and appropriate Makefiles in
``docs/build/latex`` and afterwards run ``pdflatex`` to generate PDFs.

If everything works smoothly three documents will be generated:

1) The Tutorial (``tutorial.pdf``)

2) The Reference (``reference.pdf``)

3) The whole documentation (``grokdocs.pdf``)

which can be found in ``docs/build/latex``.

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

The ``grokdocs2...`` scripts generated in ``bin/`` unfortunately yet
do not accept much options. In fact they accept no options at all. But
you can use the also generated script ``bin/sphinx-build`` to finetune
parameters or, after running ``grokdocs2...`` change to the ``build/``
directory and run for instance::

    $ make html SPHINXOPTS="-E -a"

to regenerate all docs in HTML format.


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

Beside passing options to Spinx (see above), the general settings of
documentation generated by ``sphinx`` 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.

The structure of the HTML entry page is defined in
``build/docindex.template``, which is a template for the Jinja
templating engine used by Sphinx.

The layout details are defined in ``docs/_static/grok.css``.