diff options
Diffstat (limited to 'doc/usage/builders/index.rst')
| -rw-r--r-- | doc/usage/builders/index.rst | 565 |
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. |