[Grok-dev] GrokDocs or: documentation for lazy developers
uli at gnufix.de
Wed Feb 27 10:17:33 EST 2008
I just created a new branch in the repository:
It contains a normal Grok branch with a completely restructured
documentation toolchain for the Grok documentation based on the new
Python doc toolchain and powered by Georg Brandls wonderful ``sphinx``
This means, that you can generate local Grok documentation in different
formats (HTML/LaTeX/PDF) just like the Python documentation
out-of-the-box. The result looks like this:
and offers the PDFs as download links.
This documentation naturally only includes _local_ documentation, i.e.
docs put in the docs/ directory of Grok.
Nearly all building stuff for documentation was moved to doc/build/.
How to build docs with grokdocs:
Checkout the branch::
$ svn co svn://svn.zope.org/grok/branches/ulif-grokdocs grokdocs
and build the usual things::
$ cd grokdocs
$ python2.4 bootstrap/bootstrap.py
This generates new scripts `grokdocs2html` and `grokdocs2latex`. Run
<Lots of output>
<Lots of output>
The results will be in ``docs/build/html`` and ``docs/build/latex``
$ ./bin/grokdocs2html -h
to see the options provided.
If you want to have PDFs (reference.pdf, tutorial.pdf, grokdocs.pdf), go
to docs/build/latex and run ``make``::
$ cd docs/build/latex
There's some work in progress, but you should get some usable output.
The HTML-Layout is not very fancy, but might serve. Georg Brandl was
very helpful in fixing some quirks and the work is still in progress.
Some might ask: why do we need another documentation? Isn't there
enough, newer and more documention on http://grok.zope.org ? Doesn't
maintaining ``grokdocs`` mean more complications?
Well, it might and I am open to discuss the pros and cons. The main
purpose of ``grokdocs``, however, is to provide documentation that
1) can be accessed without internet connection (once build)
2) offers a convenient method to let people test their restructured
text documents before submitting
3) provides a set of carefully reviewed docs
4) provides LaTeX/PDF support.
Furthermore it might serve as a documentation engine for user docs in
the future, because it basically can generate any docs, not just the
I could imagine a grokproject setup, where you can write tests easily
with z3c.testsetup as REStructuredText docs and afterwards build a
browsable and printable documentation out of it with grokdocs.
Please tell me, what you think!
More information about the Grok-dev