diff options
Diffstat (limited to 'doc/usage/builders')
| -rw-r--r-- | doc/usage/builders/index.rst | 95 |
1 files changed, 78 insertions, 17 deletions
diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index ce2c5dc..e293399 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -10,17 +10,70 @@ Builders 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 +The builder's "name" must be given to the **-M** or **-b** command-line options of :program:`sphinx-build` to select a builder. +The most common builders are: + +**html** + Build HTML pages. This is the default builder. + +**dirhtml** + Build HTML pages, but with a single directory per document. Makes for + prettier URLs (no ``.html``) if served from a webserver. + +**singlehtml** + Build a single HTML with the whole content. + +**htmlhelp**, **qthelp**, **devhelp**, **epub** + Build HTML files with additional information for building a documentation + collection in one of these formats. + +**applehelp** + Build an Apple Help Book. Requires :program:`hiutil` and + :program:`codesign`, which are not Open Source and presently only + available on Mac OS X 10.6 and higher. + +**latex** + Build LaTeX sources that can be compiled to a PDF document using + :program:`pdflatex`. + +**man** + Build manual pages in groff format for UNIX systems. + +**texinfo** + Build Texinfo files that can be processed into Info files using + :program:`makeinfo`. + +**text** + Build plain text files. + +**gettext** + Build gettext-style message catalogs (``.pot`` files). + +**doctest** + Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest` + extension is enabled. + +**linkcheck** + Check the integrity of all external links. + +**xml** + Build Docutils-native XML files. + +**pseudoxml** + Build compact pretty-printed "pseudo-XML" files displaying the + internal structure of the intermediate document trees. + +-------------- .. 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. + files, complete with style sheets and optionally the reStructuredText 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 @@ -146,7 +199,7 @@ The builder's "name" must be given to the **-b** command-line option of 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>`_. + `<https://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_. The builder creates *EPUB 3* files. .. autoattribute:: name @@ -184,6 +237,8 @@ The builder's "name" must be given to the **-b** command-line option of * ``texlive-latex-recommended`` * ``texlive-fonts-recommended`` + * ``texlive-fonts-extra`` (needed for ``fontawesome5``, see the 7.4.0 + change notice below) * ``tex-gyre`` (if :confval:`latex_engine` left to default) * ``texlive-latex-extra`` * ``latexmk`` @@ -191,6 +246,12 @@ The builder's "name" must be given to the **-b** command-line option of .. versionchanged:: 4.0.0 TeX Gyre fonts now required for ``'pdflatex'`` engine (default). + .. versionchanged:: 7.4.0 + LaTeX package ``xcolor`` is now required (it is part of Ubuntu + ``texlive-latex-recommended`` anyhow). The LaTeX package + ``fontawesome5`` is recommended. See the :ref:`'sphinxsetup' + <latexsphinxsetup>` ``iconpackage`` key for more. + Additional packages are needed in some circumstances: * ``texlive-lang-cyrillic`` for Cyrillic (and also then @@ -245,9 +306,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. 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. + This builder produces a text file for each reStructuredText file. + This is almost the same as the reStructuredText source, + but with much of the markup stripped for better readability. .. autoattribute:: name @@ -300,8 +361,8 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. 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. + (``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:: @@ -319,10 +380,10 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. attribute:: implementation - A module that implements `dump()`, `load()`, `dumps()` and `loads()` + 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. + ``simplejson``, ``phpserialize``, ``plistlib``, and others. .. attribute:: out_suffix @@ -400,9 +461,9 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. .. 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. + :rst:dir:`versionchanged`, :rst:dir:`deprecated` and :rst:dir:`versionremoved` + directives for the current :confval:`version`. This is useful to generate a + changelog file, for example. .. autoattribute:: name @@ -487,8 +548,8 @@ 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. +files. They also copy the reStructuredText source files +to the ``_sources`` directory under the output directory. The :class:`.PickleHTMLBuilder` is a builtin subclass that implements the pickle serialization interface. |