mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
doc: Add "builders" to usage guide
This is placed in a directory as this document will eventually be split up. However, this is not the day to do this. Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane
536
doc/usage/builders/index.rst
Normal file
536
doc/usage/builders/index.rst
Normal file
@@ -0,0 +1,536 @@
|
||||
.. _builders:
|
||||
|
||||
========
|
||||
Builders
|
||||
========
|
||||
|
||||
.. module:: sphinx.builders
|
||||
: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.
|
||||
|
||||
|
||||
.. module:: sphinx.builders.html
|
||||
.. 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.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. class:: DirectoryHTMLBuilder
|
||||
|
||||
This is a subclass of the standard HTML builder. Its output is a directory
|
||||
with HTML files, where each file is called ``index.html`` and placed in a
|
||||
subdirectory named like its page name. For example, the document
|
||||
``markup/rest.rst`` will not result in an output file ``markup/rest.html``,
|
||||
but ``markup/rest/index.html``. When generating links between pages, the
|
||||
``index.html`` is omitted, so that the URL would look like ``markup/rest/``.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. class:: SingleFileHTMLBuilder
|
||||
|
||||
This is an HTML builder that combines the whole project in one output file.
|
||||
(Obviously this only works with smaller projects.) The file is named like
|
||||
the master document. No indices will be generated.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. module:: sphinx.builders.htmlhelp
|
||||
.. 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.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. module:: sphinx.builders.qthelp
|
||||
.. class:: QtHelpBuilder
|
||||
|
||||
This builder produces the same output as the standalone HTML builder, but
|
||||
also generates `Qt help`_ collection support files that allow the Qt
|
||||
collection generator to compile them.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html
|
||||
|
||||
.. module:: sphinx.builders.applehelp
|
||||
.. class:: AppleHelpBuilder
|
||||
|
||||
This builder produces an Apple Help Book based on the same output as the
|
||||
standalone HTML builder.
|
||||
|
||||
If the source directory contains any ``.lproj`` folders, the one
|
||||
corresponding to the selected language will have its contents merged with
|
||||
the generated output. These folders will be ignored by all other
|
||||
documentation types.
|
||||
|
||||
In order to generate a valid help book, this builder requires the command
|
||||
line tool :program:`hiutil`, which is only available on Mac OS X 10.6 and
|
||||
above. You can disable the indexing step by setting
|
||||
:confval:`applehelp_disable_external_tools` to ``True``, in which case the
|
||||
output will not be valid until :program:`hiutil` has been run on all of the
|
||||
``.lproj`` folders within the bundle.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
.. module:: sphinx.builders.devhelp
|
||||
.. class:: DevhelpBuilder
|
||||
|
||||
This builder produces the same output as the standalone HTML builder, but
|
||||
also generates `GNOME Devhelp <https://wiki.gnome.org/Apps/Devhelp>`__
|
||||
support file that allows the GNOME Devhelp reader to view them.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. module:: sphinx.builders.epub3
|
||||
.. class:: Epub3Builder
|
||||
|
||||
This builder produces the same output as the standalone HTML builder, but
|
||||
also generates an *epub* file for ebook readers. See :ref:`epub-faq` for
|
||||
details about it. For definition of the epub format, have a look at
|
||||
`<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
|
||||
The builder creates *EPUB 3* files.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
|
||||
Since Sphinx-1.5, the epub3 builder is used for the default builder of
|
||||
epub.
|
||||
|
||||
.. module:: sphinx.builders.latex
|
||||
.. 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.
|
||||
|
||||
The produced LaTeX file uses several LaTeX packages that may not be present
|
||||
in a "minimal" TeX distribution installation. For example, on Ubuntu, the
|
||||
following packages need to be installed for successful PDF builds:
|
||||
|
||||
* ``texlive-latex-recommended``
|
||||
* ``texlive-fonts-recommended``
|
||||
* ``texlive-latex-extra``
|
||||
* ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X)
|
||||
* ``latex-xcolor`` (old Ubuntu)
|
||||
* ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`)
|
||||
|
||||
The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
|
||||
mentioned packages, which are from a TeXLive 2013 snapshot dated
|
||||
February 2014.
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
|
||||
|
||||
.. note::
|
||||
|
||||
Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This
|
||||
makes sure the needed number of runs is automatically executed to get
|
||||
the cross-references, bookmarks, indices, and tables of contents right.
|
||||
|
||||
One can pass to ``latexmk`` options via the ``LATEXMKOPTS``
|
||||
Makefile variable. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXMKOPTS="-silent"
|
||||
|
||||
reduces console output to a minimum.
|
||||
|
||||
Also, if ``latexmk`` version is 4.52b or higher (Jan 17)
|
||||
``LATEXMKOPTS="-xelatex"`` will speed up PDF builds via XeLateX in case
|
||||
of numerous graphics inclusions.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXMKOPTS="-xelatex"
|
||||
|
||||
To pass options directly to the ``(pdf|xe|lua)latex`` executable, use
|
||||
variable ``LATEXOPTS``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXOPTS="--interaction=nonstopmode"
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
|
||||
name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
|
||||
|
||||
.. _rinohtype: https://github.com/brechtm/rinohtype
|
||||
.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
|
||||
|
||||
.. module:: sphinx.builders.text
|
||||
.. 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.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 0.4
|
||||
|
||||
.. module:: sphinx.builders.manpage
|
||||
.. class:: ManualPageBuilder
|
||||
|
||||
This builder produces manual pages in the groff format. You have to specify
|
||||
which documents are to be included in which manual pages via the
|
||||
:confval:`man_pages` configuration value.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
|
||||
.. module:: sphinx.builders.texinfo
|
||||
.. class:: TexinfoBuilder
|
||||
|
||||
This builder produces Texinfo files that can be processed into Info files by
|
||||
the :program:`makeinfo` program. You have to specify which documents are to
|
||||
be included in which Texinfo files via the :confval:`texinfo_documents`
|
||||
configuration value.
|
||||
|
||||
The Info format is the basis of the on-line help system used by GNU Emacs and
|
||||
the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more
|
||||
details. The Texinfo format is the official documentation system used by the
|
||||
GNU project. More information on Texinfo can be found at
|
||||
`<https://www.gnu.org/software/texinfo/>`_.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
|
||||
.. currentmodule:: sphinx.builders.html
|
||||
.. 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 concrete subclass of this builder serializing to the `PHP serialization`_
|
||||
format could look like this::
|
||||
|
||||
import phpserialize
|
||||
|
||||
class PHPSerializedBuilder(SerializingHTMLBuilder):
|
||||
name = 'phpserialized'
|
||||
implementation = phpserialize
|
||||
out_suffix = '.file.phpdump'
|
||||
globalcontext_filename = 'globalcontext.phpdump'
|
||||
searchindex_filename = 'searchindex.phpdump'
|
||||
|
||||
.. _PHP serialization: https://pypi.org/project/phpserialize/
|
||||
|
||||
.. 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`, `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:: 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.
|
||||
|
||||
See :ref:`serialization-details` for details about the output format.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
The old name ``web`` still works as well.
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
The file suffix is ``.fpickle``. The global context is called
|
||||
``globalcontext.pickle``, the search index ``searchindex.pickle``.
|
||||
|
||||
.. class:: JSONHTMLBuilder
|
||||
|
||||
This builder produces a directory with JSON 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.
|
||||
|
||||
See :ref:`serialization-details` for details about the output format.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
The file suffix is ``.fjson``. The global context is called
|
||||
``globalcontext.json``, the search index ``searchindex.json``.
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
.. module:: sphinx.builders.gettext
|
||||
.. class:: MessageCatalogBuilder
|
||||
|
||||
This builder produces gettext-style message catalogs. Each top-level file or
|
||||
subdirectory grows a single ``.pot`` catalog template.
|
||||
|
||||
See the documentation on :ref:`intl` for further reference.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
.. module:: sphinx.builders.changes
|
||||
.. class:: ChangesBuilder
|
||||
|
||||
This builder produces an HTML overview of all :rst:dir:`versionadded`,
|
||||
:rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the
|
||||
current :confval:`version`. This is useful to generate a ChangeLog file, for
|
||||
example.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. module:: sphinx.builders.dummy
|
||||
.. class:: DummyBuilder
|
||||
|
||||
This builder produces no output. The input is only parsed and checked for
|
||||
consistency. This is useful for linting purposes.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.4
|
||||
|
||||
.. module:: sphinx.builders.linkcheck
|
||||
.. class:: CheckExternalLinksBuilder
|
||||
|
||||
This builder scans all documents for external links, tries to open them with
|
||||
``requests``, and writes an overview which ones are broken and redirected to
|
||||
standard output and to :file:`output.txt` in the output directory.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
|
||||
Since Sphinx-1.5, the linkcheck builder comes to use requests module.
|
||||
|
||||
.. module:: sphinx.builders.xml
|
||||
.. class:: XMLBuilder
|
||||
|
||||
This builder produces Docutils-native XML files. The output can be
|
||||
transformed with standard XML tools such as XSLT processors into arbitrary
|
||||
final forms.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
.. class:: PseudoXMLBuilder
|
||||
|
||||
This builder is used for debugging the Sphinx/Docutils "Reader to Transform
|
||||
to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files
|
||||
where nesting is indicated by indentation (no end-tags). External
|
||||
attributes for all elements are output, and internal attributes for any
|
||||
leftover "pending" elements are also given.
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
.. autoattribute:: format
|
||||
|
||||
.. autoattribute:: supported_image_types
|
||||
|
||||
.. versionadded:: 1.2
|
||||
|
||||
|
||||
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``
|
||||
:confval:`html_style`.
|
||||
|
||||
``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.
|
||||
|
||||
.. todo:: Document common members.
|
||||
|
||||
Unlike the other pickle files this pickle file requires that the ``sphinx``
|
||||
package is available on unpickling.
|
||||
@@ -444,7 +444,7 @@ candidates. For instance, if the file name ``gnu.*`` was given and two files
|
||||
:file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX
|
||||
builder would choose the former, while the HTML builder would prefer the
|
||||
latter. Supported image types and choosing priority are defined at
|
||||
:ref:`builders`.
|
||||
:doc:`/usage/builders/index`.
|
||||
|
||||
Note that image file names should not contain spaces.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user