IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation of latex builder (#10925)

Browse Source
This commit is contained in:
Jean-François B
2022-10-17 10:54:31 +02:00
committed by GitHub
parent ae42de48eb
commit 78cf903bc1
1 changed files with 34 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
doc/usage/builders/index.rst
View File

@@ -165,54 +165,51 @@ The builder's "name" must be given to the **-b** command-line option of
.. module:: sphinx.builders.latex
.. class:: LaTeXBuilder
This builder produces a bunch of LaTeX files in the output directory. You
have to specify which documents are to be included in which LaTeX files via
the :confval:`latex_documents` configuration value. There are a few
configuration values that customize the output of this builder, see the
chapter :ref:`latex-options` for details.
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.
The produced LaTeX file uses several LaTeX packages that may not be present
in a "minimal" TeX distribution installation.
See :confval:`latex_documents` and the chapter :ref:`latex-options` for
available options.
On Ubuntu xenial, the following packages need to be installed for
successful PDF builds:
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` is ``'pdflatex'``)
* ``tex-gyre`` (if :confval:`latex_engine` left to default)
* ``texlive-latex-extra``
* ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
for functioning of ``make latexpdf``)
Additional packages are needed in some circumstances (see the discussion of
the ``'fontpkg'`` key of :confval:`latex_elements` for more information):
* ``texlive-lang-cyrillic`` for Cyrillic (even individual letters), and,
``cm-super`` or ``cm-super-minimal`` (if default fonts),
* ``texlive-lang-greek`` for Greek (even individual letters), and,
``cm-super`` or ``cm-super-minimal`` (if 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 ``'xelatex'``
or ``'lualatex'``.
The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
is based on a TeXLive 2015 snapshot dated March 2016.
.. versionchanged:: 1.6
Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
.. versionchanged:: 2.0
Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
* ``latexmk``
.. versionchanged:: 4.0.0
TeX Gyre fonts dependency for the default LaTeX font configuration.
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 ``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.
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: