doc: Rework "builders" document

There are a number of cleanup items.

- Some paragraphs are reworded or clarified
- Semantic markup is added where possible
- Everything is wrapped to ~80 characters

A number of TODOs are inserted. These will be resolved separately.

Signed-off-by: Stephen Finucane <stephen@that.guru>
This commit is contained in:
Stephen Finucane 2018-02-06 11:25:43 +00:00
parent f61593b535
commit 7e27e09493

View File

@ -1,7 +1,8 @@
.. _builders:
Available builders
==================
========
Builders
========
.. module:: sphinx.builders
:synopsis: Available built-in builder classes.
@ -75,8 +76,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. 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.
also generates `Qt help`_ collection support files that allow the Qt
collection generator to compile them.
.. autoattribute:: name
@ -144,7 +145,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. versionchanged:: 1.5
Since Sphinx-1.5, the epub3 builder is used for the default builder of epub.
Since Sphinx-1.5, the epub3 builder is used for the default builder of
epub.
.. module:: sphinx.builders.latex
.. class:: LaTeXBuilder
@ -159,12 +161,12 @@ The builder's "name" must be given to the **-b** command-line option of
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`)
* ``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
@ -178,7 +180,7 @@ The builder's "name" must be given to the **-b** command-line option of
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:
@ -311,7 +313,6 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
The filename for the search index Sphinx generates.
See :ref:`serialization-details` for details about the output format.
.. versionadded:: 0.5