*********************
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.

In the online version of these documents, you can submit comments and suggest
changes directly on the documentation pages.

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 Python 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
HTMLHelp formats. The latter is currently not supported by grokdocs.

The ``grokdocs`` module provides wrappers for ``sphinx``.


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. If
you want PDF docs, you have to perform two steps.

1) Run::

      $ bin/grokdocs2latex

   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 three documents:

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.

You can run each of the scripts with the `-h` option to see other
available options. The new documentation toolchain is basically able
to build **any** documentation, not just the Grok documentation.


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

The general settings of documentation generated by ``sphinx`` and
``grokdocs`` 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``.

