[Checkins] SVN: Sandbox/ulif/grok-reference-with-rest3/doc/README.rst Tell something about grokdocs.

[Uli Fouquet]

Log message for revision 84332:
  Tell something about grokdocs.

Changed:
  U   Sandbox/ulif/grok-reference-with-rest3/doc/README.rst

-=-
Modified: Sandbox/ulif/grok-reference-with-rest3/doc/README.rst
===================================================================
--- Sandbox/ulif/grok-reference-with-rest3/doc/README.rst	2008-02-27 13:22:25 UTC (rev 84331)
+++ Sandbox/ulif/grok-reference-with-rest3/doc/README.rst	2008-02-27 13:23:01 UTC (rev 84332)
@@ -1,8 +1,7 @@
-=====================
+*********************
 About these documents
-=====================
+*********************
 
-
 These documents are generated from `reStructuredText
 <http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, an excellent
 document processor specifically written for the Python documentation
@@ -27,4 +26,76 @@
 .. include:: ACKS.txt
 
 It is only with the input and contributions of the Grok community
-that Grok has so much documentation -- Thank You!
\ No newline at end of file
+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.
+
+1) Run::
+
+      $ bin/grokdocs2latex
+
+   which will generate .tex files and appropriate Makefiles in
+   ``docs/build/latex``.
+
+2) Then change to ``docs/buid/latex`` and do::
+
+   $ make
+
+The latter will run `pdflatex` to generate three documents:
+
+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.
+
+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``.
+