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