From 7e27e09493096a20c30702b410a24ab330ecea10 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 6 Feb 2018 11:25:43 +0000 Subject: [PATCH] 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 --- doc/builders.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index d968f209f..ee0aa0a33 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -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