[Grok-dev] GrokDocs or: documentation for lazy developers

[Uli Fouquet]

Hi there,

I just created a new branch in the repository:

   http://svn.zope.org/grok/branches/ulif-grokdocs/

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``
engine (http://svn.python.org/projects/doctools/trunk/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:

  https://gf1.gnufix.de/~uli/grok/docs/

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
   $ ./bin/buildout

This generates new scripts `grokdocs2html` and `grokdocs2latex`. Run
them::

   $ ./bin/grokdocs2html
   <Lots of output>

   $ ./bin/grokdocs2latex
   <Lots of output>

The results will be in ``docs/build/html`` and ``docs/build/latex``
respectively. Run 

   $ ./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
   $ make

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.


Motivation
----------

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
Grok docs. 

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!

Kind regards,

-- 
Uli