mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
216 lines
7.0 KiB
ReStructuredText
216 lines
7.0 KiB
ReStructuredText
.. _builders:
|
|
|
|
Available builders
|
|
==================
|
|
|
|
.. module:: sphinx.builder
|
|
:synopsis: Available built-in builder classes.
|
|
|
|
These are the built-in Sphinx builders. More builders can be added by
|
|
:ref:`extensions <extensions>`.
|
|
|
|
The builder's "name" must be given to the **-b** command-line option of
|
|
:program:`sphinx-build` to select a builder.
|
|
|
|
|
|
.. class:: StandaloneHTMLBuilder
|
|
|
|
This is the standard HTML builder. Its output is a directory with HTML
|
|
files, complete with style sheets and optionally the reST sources. There are
|
|
quite a few configuration values that customize the output of this builder,
|
|
see the chapter :ref:`html-options` for details.
|
|
|
|
Its name is ``html``.
|
|
|
|
.. class:: HTMLHelpBuilder
|
|
|
|
This builder produces the same output as the standalone HTML builder, but
|
|
also generates HTML Help support files that allow the Microsoft HTML Help
|
|
Workshop to compile them into a CHM file.
|
|
|
|
Its name is ``htmlhelp``.
|
|
|
|
.. class:: PickleHTMLBuilder
|
|
|
|
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. It also
|
|
is the format used by the Sphinx Web application.
|
|
|
|
See :ref:`serialization-details` for details about the output format.
|
|
|
|
Its name is ``pickle``. (The old name ``web`` still works as well.)
|
|
|
|
The file suffix is ``.fpickle``. The global context is called
|
|
``globalcontext.pickle``, the search index ``searchindex.pickle``.
|
|
|
|
.. class:: LaTeXBuilder
|
|
|
|
This builder produces a bunch of LaTeX files in the output directory. You
|
|
have to specify which documents are to be included in which LaTeX files via
|
|
the :confval:`latex_documents` configuration value. There are a few
|
|
configuration values that customize the output of this builder, see the
|
|
chapter :ref:`latex-options` for details.
|
|
|
|
Its name is ``latex``.
|
|
|
|
.. class:: TextBuilder
|
|
|
|
This builder produces a text file for each reST file -- this is almost the
|
|
same as the reST source, but with much of the markup stripped for better
|
|
readability.
|
|
|
|
Its name is ``text``.
|
|
|
|
.. versionadded:: 0.4
|
|
|
|
.. class:: SerializingHTMLBuilder
|
|
|
|
This builder uses a module that implements the Python serialization API
|
|
(`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
|
|
HTML documentation. The pickle builder is a subclass of it.
|
|
|
|
A concreate subclass of this builder serializing to JSON could look like
|
|
this::
|
|
|
|
import simplejson
|
|
|
|
classs JSONBuilder(SerializingHTMLBuilder):
|
|
name = 'json'
|
|
implementation = simplejson
|
|
out_suffix = '.fjson'
|
|
globalcontext_filename = 'globalcontext.json'
|
|
searchindex_filename = 'searchindex.json'
|
|
|
|
.. attribute:: implementation
|
|
|
|
A module that implements `dump()`, `load()`, `dumps()` and `loads()`
|
|
functions that conform to the functions with the same names from the
|
|
pickle module. Known modules implementing this interface are
|
|
`simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`,
|
|
and others.
|
|
|
|
.. attribute:: out_suffix
|
|
|
|
The suffix for all regular files.
|
|
|
|
.. attribute:: globalcontext_filename
|
|
|
|
The filename for the file that contains the "global context". This
|
|
is a dict with some general configuration values such as the name
|
|
of the project.
|
|
|
|
.. attribute:: searchindex_filename
|
|
|
|
The filename for the search index Sphinx generates.
|
|
|
|
|
|
See :ref:`serialization-details` for details about the output format.
|
|
|
|
.. versionadded:: 0.5
|
|
|
|
.. class:: ChangesBuilder
|
|
|
|
This builder produces an HTML overview of all :dir:`versionadded`,
|
|
:dir:`versionchanged` and :dir:`deprecated` directives for the current
|
|
:confval:`version`. This is useful to generate a ChangeLog file, for
|
|
example.
|
|
|
|
Its name is ``changes``.
|
|
|
|
.. class:: CheckExternalLinksBuilder
|
|
|
|
This builder scans all documents for external links, tries to open them with
|
|
:mod:`urllib2`, and writes an overview which ones are broken and redirected
|
|
to standard output and to :file:`output.txt` in the output directory.
|
|
|
|
Its name is ``linkcheck``.
|
|
|
|
|
|
Built-in Sphinx extensions that offer more builders are:
|
|
|
|
* :mod:`~sphinx.ext.doctest`
|
|
* :mod:`~sphinx.ext.coverage`
|
|
|
|
|
|
.. _serialization-details:
|
|
|
|
Serialization builder details
|
|
-----------------------------
|
|
|
|
All serialization builders outputs one file per source file and a few special
|
|
files. They also copy the reST source files in the directory ``_sources``
|
|
under the output directory.
|
|
|
|
The :class:`PickleHTMLBuilder` is a builtin subclass that implements the pickle
|
|
serialization interface.
|
|
|
|
The files per source file have the extensions of
|
|
:attr:`~SerializingHTMLBuilder.out_suffix`, and are arranged in directories
|
|
just as the source files are. They unserialize to a dictionary (or dictionary
|
|
like structure) 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:
|
|
|
|
:attr:`SerializingHTMLBuilder.globalcontext_filename`
|
|
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.
|
|
|
|
:attr:`SerializingHTMLBuilder.searchindex_filename`
|
|
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.
|
|
|
|
``environment.pickle``
|
|
The build environment. This is always a pickle file, independent of the
|
|
builder and a copy of the environment that was used when the builder was
|
|
started. (XXX: document common members)
|
|
|
|
Unlike the other pickle files this pickle file requires that the sphinx
|
|
module is available on unpickling.
|