summaryrefslogtreecommitdiffstats
path: root/doc/usage/builders
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-15 17:25:40 +0000
commitcf7da1843c45a4c2df7a749f7886a2d2ba0ee92a (patch)
tree18dcde1a8d1f5570a77cd0c361de3b490d02c789 /doc/usage/builders
parentInitial commit. (diff)
downloadsphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.tar.xz
sphinx-cf7da1843c45a4c2df7a749f7886a2d2ba0ee92a.zip
Adding upstream version 7.2.6.upstream/7.2.6
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/usage/builders')
-rw-r--r--doc/usage/builders/index.rst565
1 files changed, 565 insertions, 0 deletions
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst
new file mode 100644
index 0000000..ce2c5dc
--- /dev/null
+++ b/doc/usage/builders/index.rst
@@ -0,0 +1,565 @@
+.. _builders:
+
+========
+Builders
+========
+
+.. module:: sphinx.builders
+ :synopsis: Available built-in builder classes.
+
+These are the built-in Sphinx builders. More builders can be added by
+:doc:`extensions </usage/extensions/index>`.
+
+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
+
+.. module:: sphinx.builders.dirhtml
+.. 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
+
+.. module:: sphinx.builders.singlehtml
+.. 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 root document. No indices will be generated.
+
+ .. autoattribute:: name
+
+ .. autoattribute:: format
+
+ .. autoattribute:: supported_image_types
+
+ .. versionadded:: 1.0
+
+.. module:: sphinxcontrib.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:: sphinxcontrib.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.
+
+ .. versionchanged:: 2.0
+
+ Moved to sphinxcontrib.qthelp from sphinx.builders package.
+
+ .. autoattribute:: name
+
+ .. autoattribute:: format
+
+ .. autoattribute:: supported_image_types
+
+ .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html
+
+.. module:: sphinxcontrib.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
+
+ .. versionchanged:: 2.0
+
+ Moved to sphinxcontrib.applehelp from sphinx.builders package.
+
+.. module:: sphinxcontrib.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
+
+ .. versionchanged:: 2.0
+
+ Moved to sphinxcontrib.devhelp from sphinx.builders package.
+
+.. 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 as the default epub builder.
+
+.. module:: sphinx.builders.latex
+.. class:: LaTeXBuilder
+
+ This builder produces LaTeX source files in the output directory. The
+ actual PDF builds happen inside this output directory and need to be
+ triggered in a second step. This can be done via
+ :program:`make all-pdf` there.
+ To combine the two steps into only one, use :option:`sphinx-build -M`
+ (i.e. ``-M latexpdf`` not ``-b latexpdf``) or :program:`make latexpdf`
+ at the project root.
+
+ See :confval:`latex_documents` and the chapter :ref:`latex-options` for
+ available options.
+
+ PDF builds need a sufficiently complete LaTeX installation.
+ The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS,
+ whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04,
+ but PDF builds can be successfully done on much older LaTeX installations.
+
+ At any rate, on Ubuntu for example, following packages must all be present:
+
+ * ``texlive-latex-recommended``
+ * ``texlive-fonts-recommended``
+ * ``tex-gyre`` (if :confval:`latex_engine` left to default)
+ * ``texlive-latex-extra``
+ * ``latexmk``
+
+ .. versionchanged:: 4.0.0
+ TeX Gyre fonts now required for ``'pdflatex'`` engine (default).
+
+ Additional packages are needed in some circumstances:
+
+ * ``texlive-lang-cyrillic`` for Cyrillic (and also then
+ ``cm-super`` if using the default fonts),
+ * ``texlive-lang-greek`` for Greek (and also then
+ ``cm-super`` if using the default fonts),
+ * ``texlive-xetex`` if :confval:`latex_engine` is ``'xelatex'``,
+ * ``texlive-luatex`` if :confval:`latex_engine` is ``'lualatex'``,
+ * ``fonts-freefont-otf`` if :confval:`latex_engine` is either
+ ``'xelatex'`` or ``'lualatex'``.
+
+ .. note::
+
+ Since 1.6, ``make latexpdf`` uses on GNU/Linux and macOS
+ :program:`latexmk`, as it
+ makes sure the needed number of runs is automatically executed.
+ On Windows the PDF builds execute a fix number of LaTeX runs
+ (three, then ``makeindex``, then two more).
+
+ 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`` is at version 4.52b or higher (January 2017)
+ ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
+ of numerous graphics inclusions.
+
+ To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
+ variable ``LATEXOPTS``, for example:
+
+ .. code-block:: console
+
+ make latexpdf LATEXOPTS="--halt-on-error"
+
+ .. 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: https://www.mos6581.org/rinohtype/master/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:: sphinxcontrib.serializinghtml
+.. 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 uses the requests module.
+
+ .. versionchanged:: 3.4
+
+ The linkcheck builder retries links when servers apply rate limits.
+
+.. 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.