[Python-checkins] r61908 - in doctools/trunk/doc: builders.rst ext/builderapi.rst templating.rst

[georg.brandl]

Author: georg.brandl
Date: Tue Mar 25 20:20:26 2008
New Revision: 61908

Modified:
   doctools/trunk/doc/builders.rst
   doctools/trunk/doc/ext/builderapi.rst
   doctools/trunk/doc/templating.rst
Log:
Expand on the pickle builder.


Modified: doctools/trunk/doc/builders.rst
==============================================================================
--- doctools/trunk/doc/builders.rst	(original)
+++ doctools/trunk/doc/builders.rst	Tue Mar 25 20:20:26 2008
@@ -34,10 +34,12 @@
 
    This builder produces a directory with pickle files containing mostly HTML
    fragments and TOC information, for use of a web application (or custom
-   postprocessing tool) that doesn't use the standard HTML templates.
+   postprocessing tool) that doesn't use the standard HTML templates.  It also
+   is the format used by the Sphinx Web application.
 
-   It also is the format used by the Sphinx Web application.  Its name is
-   ``pickle``.  (The old name ``web`` still works as well.)
+   See :ref:`pickle-details` for details about the output format.
+
+   Its name is ``pickle``.  (The old name ``web`` still works as well.)
 
 .. class:: LaTeXBuilder
 
@@ -71,3 +73,76 @@
 
 * :mod:`~sphinx.ext.doctest`
 * :mod:`~sphinx.ext.coverage`
+
+
+.. _pickle-details:
+
+Pickle builder details
+----------------------
+
+The builder outputs one pickle file per source file, and a few special files.
+It also copies the reST source files in the directory ``_sources`` under the
+output directory.
+
+The files per source file have the extensions ``.fpickle``, and are arranged in
+directories just as the source files are.  They unpickle to a dictionary with
+these keys:
+
+``body``
+   The HTML "body" (that is, the HTML rendering of the source file), as rendered
+   by the HTML translator.
+
+``title``
+   The title of the document, as HTML (may contain markup).
+
+``toc``
+   The table of contents for the file, rendered as an HTML ``<ul>``.
+
+``display_toc``
+   A boolean that is ``True`` if the ``toc`` contains more than one entry.
+
+``current_page_name``
+   The document name of the current file.
+
+``parents``, ``prev`` and ``next``
+   Information about related chapters in the TOC tree.  Each relation is a
+   dictionary with the keys ``link`` (HREF for the relation) and ``title``
+   (title of the related document, as HTML).  ``parents`` is a list of
+   relations, while ``prev`` and ``next`` are a single relation.
+
+``sourcename``
+   The name of the source file under ``_sources``.
+
+The special files are located in the root output directory.  They are:
+
+``environment.pickle``
+   The build environment.  (XXX add important environment properties)
+
+``globalcontext.pickle``
+   A pickled dict with these keys:
+
+   ``project``, ``copyright``, ``release``, ``version``
+      The same values as given in the configuration file.
+
+   ``style``, ``use_modindex``
+      :confval:`html_style` and :confval:`html_use_modindex`, respectively.
+
+   ``last_updated``
+      Date of last build.
+
+   ``builder``
+      Name of the used builder, in the case of pickles this is always
+      ``'pickle'``.
+
+   ``titles``
+      A dictionary of all documents' titles, as HTML strings.
+
+``searchindex.pickle``
+   An index that can be used for searching the documentation.  It is a pickled
+   list with these entries:
+
+   * A list of indexed docnames.
+   * A list of document titles, as HTML strings, in the same order as the first
+     list.
+   * A dict mapping word roots (processed by an English-language stemmer) to a
+     list of integers, which are indices into the first list.

Modified: doctools/trunk/doc/ext/builderapi.rst
==============================================================================
--- doctools/trunk/doc/ext/builderapi.rst	(original)
+++ doctools/trunk/doc/ext/builderapi.rst	Tue Mar 25 20:20:26 2008
@@ -1,3 +1,5 @@
+.. _writing-builders:
+
 Writing new builders
 ====================
 

Modified: doctools/trunk/doc/templating.rst
==============================================================================
--- doctools/trunk/doc/templating.rst	(original)
+++ doctools/trunk/doc/templating.rst	Tue Mar 25 20:20:26 2008
@@ -8,6 +8,24 @@
 anyone having used Django will already be familiar with it.  It also has
 excellent documentation for those who need to make themselves familiar with it.
 
+
+Do I need to use Sphinx' templates to produce HTML?
+---------------------------------------------------
+
+No.  You have several other options:
+
+* You can :ref:`write a custom builder <writing-builders>` that derives from
+  :class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine
+  of choice.
+
+* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces
+  pickle files with the page contents, and postprocess them using a custom tool,
+  or use them in your Web application.
+
+
+Jinja/Sphinx Templating Primer
+------------------------------
+
 The most important concept in Jinja is :dfn:`template inheritance`, which means
 that you can overwrite only specific blocks within a template, customizing it
 while also keeping the changes at a minimum.