Official Grok Documentation version 1.5

About these documents

These documents are generated from reStructuredText sources by Sphinx, 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 project for creating reStructuredText and the docutils suite;
  • Georg Brandl for his Sphinx package.

See Reporting Bugs in Grok for information how to report bugs in Grok itself.

Contributors to the Grok Documentation

This section lists people who have contributed in some way to the Grok documentation. It is probably not complete – if you feel that you or anyone else should be on this list, please let us know (send email to grok-dev@zope.org), and we’ll be glad to correct the problem.

  • Darryl Cousins
  • Kushal Das
  • Martijn Faassen
  • Uli Fouquet
  • Jim Fulton
  • Jan-Wijbrand Kolman
  • Luis de la Parra
  • Luciano Ramalho
  • Lennart Regebro
  • Brandon Craig Rhodes
  • Kevin Teague
  • Sebastian Ware
  • Philipp von Weitershausen

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.