[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