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.
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 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 Python 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 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.
Run:
$ bin/grokdocs2latex
which will generate .tex files and appropriate Makefiles in docs/build/latex.
Then change to docs/buid/latex and do:
$ make
The latter will run pdflatex to generate three documents:
- The Tutorial (tutorial.pdf)
- The Reference (reference.pdf)
- 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.
