[Checkins] SVN: grok/branches/ulif-docs2sphinx/doc/README.rst Update README to reflect changes.

Uli Fouquet uli at gnufix.de
Wed Dec 22 05:35:28 EST 2010


Log message for revision 119055:
  Update README to reflect changes.
  

Changed:
  U   grok/branches/ulif-docs2sphinx/doc/README.rst

-=-
Modified: grok/branches/ulif-docs2sphinx/doc/README.rst
===================================================================
--- grok/branches/ulif-docs2sphinx/doc/README.rst	2010-12-22 10:35:11 UTC (rev 119054)
+++ grok/branches/ulif-docs2sphinx/doc/README.rst	2010-12-22 10:35:27 UTC (rev 119055)
@@ -3,13 +3,11 @@
 *********************
 
 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
-by Georg Brandl and contributors.
+<http://docutils.sf.net/rst.html>`_ sources by `Sphinx
+<http://sphinx.pocoo.org>`_, 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 at zope.org mailing list.  We're always looking for volunteers
 wanting to help with the docs, so feel free to send a mail there!
@@ -18,9 +16,10 @@
 
 * the `docutils <http://docutils.sf.net/>`_ project for creating
   reStructuredText and the docutils suite;
-* Georg Brandl for his `sphinx` package.
+* Georg Brandl for his `Sphinx` package.
 
-See :ref:`reporting-bugs` for information how to report bugs in Python itself.
+See :ref:`reporting-bugs` for information how to report bugs in Grok
+itself.
 
 .. including the ACKS file here so that it can be maintained separately
 .. include:: ACKS.txt
@@ -32,18 +31,15 @@
 The Grok documentation toolchain
 ================================
 
-Grok now makes use of the ``sphinx`` package, which was written by
+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.
+other formats.
 
-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::
 
@@ -53,22 +49,15 @@
 
   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.
+For LaTeX/PDF docs you must have LaTeX and ``pdflatex`` installed. Then, to generate PDF docs, run::
 
-1) Run::
+  $ bin/grokdocs2pdf
 
-      $ bin/grokdocs2latex
+which will first generate .tex files and appropriate Makefiles in
+``docs/build/latex`` and afterwards run ``pdflatex`` to generate PDFs.
 
-   which will generate .tex files and appropriate Makefiles in
-   ``docs/build/latex``.
+If everything works smoothly three documents will be generated:
 
-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``)
@@ -80,22 +69,27 @@
 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.
+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
 ---------------------------------------------------------------
 
-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.
+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``.
-



More information about the checkins mailing list