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.)
+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
+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
+ The HTML "body" (that is, the HTML rendering of the source file), as rendered
+ by the HTML translator.
+ The title of the document, as HTML (may contain markup).
+ The table of contents for the file, rendered as an HTML ``<ul>``.
+ A boolean that is ``True`` if the ``toc`` contains more than one entry.
+ 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.
+ The name of the source file under ``_sources``.
+The special files are located in the root output directory. They are:
+ The build environment. (XXX add important environment properties)
+ 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.
+ Name of the used builder, in the case of pickles this is always
+ A dictionary of all documents' titles, as HTML strings.
+ 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
+ * A dict mapping word roots (processed by an English-language stemmer) to a
+ list of integers, which are indices into the first list.