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

Make the latex docs more concise

Browse Source
This commit is contained in:
jfbu 2017-06-05 12:11:41 +02:00
parent c6699eb6b8
commit bd8c7e1410
1 changed files with 173 additions and 216 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

389
doc/latex.rst
View File

@ -33,167 +33,143 @@ The *latex* target does not benefit from pre-prepared themes like the
Basic customization
-------------------
It is available from ``conf.py`` via usage of the
:ref:`latex-options` as described in :doc:`config` (backslashes must be doubled
in Python string literals to reach latex.) For example::
It is achieved via usage of the
:ref:`latex-options` as described in :doc:`config`. For example::
# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
'fontenc': '\\usepackage{fontspec}',
'fontpkg': '''\
\\setmainfont{DejaVu Serif}
\\setsansfont{DejaVu Sans}
\\setmonofont{DejaVu Sans Mono}''',
'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}',
'preamble': '''\
\\usepackage[titles]{tocloft}
\\cftsetpnumwidth {1.25cm}\\cftsetrmarg{1.5cm}
\\setlength{\\cftchapnumwidth}{0.75cm}
\\setlength{\\cftsecindent}{\\cftchapnumwidth}
\\setlength{\\cftsecnumwidth}{1.25cm}''',
'fncychap': '\\usepackage[Bjornstrup]{fncychap}',
'printindex': '\\footnotesize\\raggedright\\printindex',
}
latex_show_urls = 'footnote'
# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
''',
'preamble': r'''
\usepackage[titles]{tocloft}
\cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
\setlength{\cftchapnumwidth}{0.75cm}
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
'printindex': r'\footnotesize\raggedright\printindex',
}
latex_show_urls = 'footnote'
.. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
.. highlight:: latex
More advanced customization will be obtained via insertion into the LaTeX
preamble of relevant ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
or ``\definecolor`` commands. The ``'preamble'`` key of
:confval:`latex_elements` will serve for inserting these commands. If they are
numerous, it may prove more convenient to assemble them into a specialized
file :file:`mystyle.tex` and then use::
If the size of the ``'preamble'`` contents become inconvenient, one may put
all needed macros into some file :file:`mystyle.tex` of the project source
repertory, and get LaTeX to import it at run time::
'preamble': r'\makeatletter\input{mystyle.tex}\makeatother',
'preamble': r'\input{mystyle.tex}',
# or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
'preamble': r'\usepackage{mystyle}',
or, better, to set up a style file
:file:`mystyle.sty` which can then be loaded via::
It is needed to set appropriately :confval:`latex_additional_files`, for
example::
'preamble': r'\usepackage{mystyle}',
The :ref:`build configuration file <build-config>` file for the project needs
to have its variable :confval:`latex_additional_files` appropriately
configured, for example::
latex_additional_files = ["mystyle.sty"]
latex_additional_files = ["mystyle.tex"]
.. _latexsphinxsetup:
The Sphinx LaTeX style package options
--------------------------------------
The LaTeX style file options
----------------------------
The ``'sphinxsetup'`` key to :confval:`latex_elements` provides a
more convenient interface to various style parameters. It is a comma separated
string of ``key=value`` instructions::
The sphinxsetup interface
~~~~~~~~~~~~~~~~~~~~~~~~~
key1=value1,key2=value2, ...
The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient
interface to the package options of the Sphinx style file::
- if a key is repeated, it is its last occurence which is used
- spaces around the commas and equal signs are ignored
latex_elements = {
'sphinxsetup': 'key1=value1, key2=value2, ...',
}
If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
- some values may be LaTeX macros, then the backslashes must be
Python-escaped, or the whole must be a Python raw string,
- LaTeX boolean keys require *lowercase* ``true`` or ``false`` values,
- spaces around the commas and equal signs are ignored, spaces inside LaTeX
macros may be significant.
\usepackage{sphinx}
\sphinxsetup{key1=value1,key2=value2,...}
If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro
inside the document preamble, like this::
\usepackage{sphinx}
\sphinxsetup{key1=value1, key2=value2,...}
.. versionadded:: 1.5
It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
directly into the body of the document, via the help of the :rst:dir:`raw`
directive. This is what is done for this documentation, for local styling
of this chapter in the PDF output::
.. raw:: latex
\begingroup
\sphinxsetup{%
verbatimwithframe=false,
VerbatimColor={named}{OldLace},
TitleColor={named}{DarkGoldenrod},
hintBorderColor={named}{LightCoral},
attentionborder=3pt,
attentionBorderColor={named}{Crimson},
attentionBgColor={named}{FloralWhite},
noteborder=2pt,
noteBorderColor={named}{Olive},
cautionborder=3pt,
cautionBorderColor={named}{Cyan},
cautionBgColor={named}{LightCyan}}
at the start of the chapter and::
.. raw:: latex
\endgroup
at its end.
.. note::
- Most options described next could also have been positioned as
:file:`sphinx.sty` package options. But for those where the key value
contains some LaTeX code the use of ``\sphinxsetup`` is mandatory. Hence
the whole ``'sphinxsetup'`` string is passed as argument to
``\sphinxsetup``.
The colors above are made available via the ``svgnames`` option of
the "xcolor" package::
- As an alternative to the ``'sphinxsetup'`` key, it is possible
to insert the ``\\sphinxsetup{key=value,..}`` inside the
``'preamble'`` key. It is even possible to use the ``\sphinxsetup`` in
the body of the document, via the :rst:dir:`raw` directive, to modify
dynamically the option values: this is actually what we did for the
duration of this chapter for the PDF output, which is styled using::
\sphinxsetup{%
verbatimwithframe=false,
VerbatimColor={named}{OldLace},
TitleColor={named}{DarkGoldenrod},
hintBorderColor={named}{LightCoral},
attentionborder=3pt,
attentionBorderColor={named}{Crimson},
attentionBgColor={named}{FloralWhite},
noteborder=2pt,
noteBorderColor={named}{Olive},
cautionborder=3pt,
cautionBorderColor={named}{Cyan},
cautionBgColor={named}{LightCyan}}
and with the ``svgnames`` option having been passed to "xcolor" package::
latex_elements = {
'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
}
latex_elements = {
'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
}
Here are the currently available options together with their default values.
.. caution::
These options correspond to what has been so far the default LaTeX
rendering by Sphinx; if in future Sphinx offers various *themes* for LaTeX,
the interface may change.
.. attention::
LaTeX requires that keys with Boolean values use **lowercase** ``true`` or
``false``.
The available styling options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _latexsphinxsetuphmargin:
``hmargin``
The dimensions of the horizontal margins. Legacy Sphinx default value is
``1in`` (which stands for ``{1in,1in}``.) It is passed over as ``hmargin``
option to ``geometry`` package.
Here is an example for non-Japanese documents of use of this key::
``hmargin, vmargin``
The dimensions of the horizontal (resp. vertical) margins, passed as
``hmargin`` (resp. ``vmargin``) option to
the ``geometry`` package. The default is ``1in``, which is equivalent to
``{1in,1in}``. Example::
'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
Japanese documents currently accept only the form with only one dimension.
This option is handled then in a special manner in order for ``geometry``
package to set the text width to an exact multiple of the *zenkaku* width
of the base document font.
Japanese documents currently accept only the one-dimension format for
these parameters. The ``geometry`` package is then passed suitable options
to get the text width set to an exact multiple of the *zenkaku* width, and
the text height set to an integer multiple of the baselineskip, with the
closest fit for the margins.
.. hint::
For a ``'manual'`` type document with :confval:`language` set to
``'ja'``, which by default uses the ``jsbook`` LaTeX document class, the
dimension units, when the pointsize isn't ``10pt``, must be so-called TeX
"true" units::
For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``,
use the ``nomag`` extra document class option (cf.
``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called
TeX "true" units:
'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
This is due to the way the LaTeX class ``jsbook`` handles the
pointsize.
Or, one uses regular units but with ``nomag`` as extra document class
option (cf. ``'extraclassoptions'`` key of :confval:`latex_elements`.)
.. versionadded:: 1.5.3
``vmargin``
The dimension of the vertical margins. Legacy Sphinx default value is
``1in`` (or ``{1in,1in}``.) Passed over as ``vmargin`` option to
``geometry``.
Japanese documents will arrange for the text height to be an integer
multiple of the baselineskip, taking the closest match suitable for the
asked-for vertical margin. It can then be only one dimension. See notice
above.
.. versionadded:: 1.5.3
``marginpar``
@ -207,17 +183,12 @@ Here are the currently available options together with their default values.
default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
includes are framed. Setting it to ``false`` does not deactivate use of
package "framed", because it is still in use for the optional background
colour (see below).
colour.
``verbatimwrapslines``
default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
contents should wrap.
.. (comment) It is theoretically possible to customize this even
more and decide at which characters a line-break can occur and whether
before or after, but this is accessible currently only by re-defining
some macros with complicated LaTeX syntax from :file:`sphinx.sty`.
``parsedliteralwraps``
default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
contents should wrap.
@ -237,29 +208,19 @@ Here are the currently available options together with their default values.
``verbatimvisiblespace``
default ``\textcolor{red}{\textvisiblespace}``. When a long code line is
split, space characters located at end of the line before the break are
displayed using this code.
split, the last space character from the source code line right before the
linebreak location is typeset using this.
``verbatimcontinued``
The default is::
A LaTeX macro inserted at start of continuation code lines. Its
(complicated...) default typesets a small red hook pointing to the right::
\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
It is printed at start of continuation lines. This rather formidable
expression reserves twice the width of a typical character in the current
(monospaced) font and puts there a small red hook pointing to the right.
.. versionchanged:: 1.5
The breaking of long code lines was introduced at 1.4.2. The space
reserved to the continuation symbol was changed at 1.5 to obey the
current font characteristics (this was needed as Sphinx 1.5 LaTeX
allows code-blocks in footnotes which use a smaller font size).
.. hint::
This specification gives the same spacing as before 1.5::
\normalfont\normalsize\makebox[3ex][r]{\textcolor{red}{\tiny$\hookrightarrow$}
The breaking of long code lines was added at 1.4.2. The default
definition of the continuation symbol was changed at 1.5 to accomodate
various font sizes (e.g. code-blocks can be in footnotes).
``TitleColor``
default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
@ -384,39 +345,31 @@ Here are the currently available options together with their default values.
``BeforeFootnote``
default ``\leavevmode\unskip``. LaTeX macros inserted before the footnote
mark. The default removes possible space before it.
It can be set to empty (``BeforeFootnote={},``) to recover the earlier
behaviour of Sphinx, or alternatively contain a ``\nobreak\space`` or a
``\thinspace`` after the ``\unskip`` to insert some chosen
(non-breakable) space.
mark. The default removes possible space before it (else, TeX could insert
a linebreak there).
.. versionadded:: 1.5
formerly, footnotes from explicit mark-up (but not automatically
generated ones) were preceded by a space in the output ``.tex`` file
hence a linebreak in PDF was possible. To avoid insertion of this space
one could use ``foo\ [#f1]`` mark-up, but this impacts all builders.
``HeaderFamily``
default ``\sffamily\bfseries``. Sets the font used by headings.
As seen above, key values may even be used for LaTeX commands. But don't
forget to double the backslashes if not using "raw" Python strings.
LaTeX macros and environments
-----------------------------
The LaTeX environments defined by Sphinx
----------------------------------------
Here are some macros from the package file :file:`sphinx.sty` and class files
:file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names
thus allowing redefinitions. Check the respective files for the defaults.
Let us now list some macros from the package file
:file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
:file:`sphinxmanual.cls`, which can be entirely redefined, if desired.
Macros
~~~~~~
- text styling commands (they have one argument): ``\sphinx<foo>`` with
``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
``optional``. The non-prefixed macros will still be defined if option
- text styling commands ``\sphinx<foo>`` with ``<foo>`` being one of
``strong``, ``bfcode``, ``email``, ``tablecontinued``, ``titleref``,
``menuselection``, ``accelerator``, ``crossref``, ``termref``, ``optional``.
The non-prefixed macros will still be defined if option
:confval:`latex_keep_old_macro_names` has been set to ``True`` (default is
``False``), in which case the prefixed macros expand to the
non-prefixed ones.
``False``), in which case the prefixed macros expand to the non-prefixed
ones.
.. versionadded:: 1.4.5
Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
@ -427,21 +380,39 @@ Let us now list some macros from the package file
already exists at ``sphinx.sty`` loading time, only the ``\sphinx``
prefixed one will be defined. The setting will be removed at 1.7.
- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
- more text styling: ``\sphinxstyle<bar>`` with ``<bar>`` one of
``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
``abbreviation``, ``literalintitle``.
``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``,
``literalstrong``, ``abbreviation``, ``literalintitle``.
.. versionadded:: 1.5
the new macros are wrappers of the formerly hard-coded ``\texttt``,
``\emph``, ... The default definitions can be found in
:file:`sphinx.sty`.
these macros were formerly hard-coded as non customizable ``\texttt``,
``\emph``, etc...
.. versionadded:: 1.6
``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows
multiple paragraphs in header cells of tables.
.. deprecated:: 1.6
macro ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
- by default the Sphinx style file ``sphinx.sty`` executes the command
``\fvset{fontsize=\small}`` as part of its configuration of
``fancyvrb.sty``. This may be overriden for example via
``\fvset{fontsize=auto}`` which will let code listings use the ambient font
size. Refer to ``fancyvrb.sty``'s documentation for further keys.
.. versionadded:: 1.5
- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
:file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
.. versionchanged:: 1.5
formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
- the ``\maketitle`` command is redefined by the class files
:file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
Environments
~~~~~~~~~~~~
- a :dudir:`figure` may have an optional legend with arbitrary body
elements: they are rendered in a ``sphinxlegend`` environment. The default
definition issues ``\small``, and ends with ``\par``.
@ -459,15 +430,17 @@ Let us now list some macros from the package file
specific to each type, which can be set via ``'sphinxsetup'`` string.
.. versionchanged:: 1.5
use of public environment names, separate customizability of the parameters.
use of public environment names, separate customizability of the
parameters, such as ``noteBorderColor``, ``noteborder``,
``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
- the :dudir:`contents` directive (with ``:local:`` option) and the
:dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
See above for the three dimensions associated with it.
.. versionadded:: 1.4.2
former code refactored into an environment allowing page breaks.
.. versionchanged:: 1.5
use of public names for the three lengths. The environment itself was
redefined to allow page breaks at release 1.4.2.
- the literal blocks (:rst:dir:`code-block` directives, etc ...), are
options ``shadowsep``, ``shadowsize``, ``shadowrule``.
- the literal blocks (via ``::`` or :rst:dir:`code-block`), are
implemented using ``sphinxVerbatim`` environment which is a wrapper of
``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
of the top caption and the wrapping of long lines, and a frame which allows
@ -476,41 +449,12 @@ Let us now list some macros from the package file
allows a caption).
.. versionchanged:: 1.5
``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning
which is the one of ``OriginalVerbatim`` too), and custom one is called
``sphinxVerbatim``. Also, earlier version of Sphinx used
``OriginalVerbatim`` inside tables (captions were lost, long code lines
were not wrapped), it now uses there ``sphinxVerbatimintable``.
``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also
under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used
inside tables.
.. versionadded:: 1.5
the two customizable lengths, the ``sphinxVerbatimintable``, the boolean
toggles described above.
- by default the Sphinx style file ``sphinx.sty`` includes the command
``\fvset{fontsize=\small}`` as part of its configuration of
``fancyvrb.sty``. The user may override this for example via
``\fvset{fontsize=auto}`` which will use for listings the ambient
font size. Refer to ``fancyvrb.sty``'s documentation for further keys.
.. versionadded:: 1.5
formerly, the use of ``\small`` for code listings was not customizable.
- the section, subsection, ... headings are set using *titlesec*'s
``\titleformat`` command. Check :file:`sphinx.sty` for the definitions.
- for the ``'sphinxmanual'`` class (corresponding to the fifth element of
:confval:`latex_documents` being set to ``'manual'``), the chapter headings
can be customized using *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``,
``\ChTitleVar``. Check :file:`sphinx.sty` for the default definitions. They
are applied only if *fncychap* is loaded with option ``Bjarne``. It is also
possible to use an empty ``'fncychap'`` key, and use the *titlesec*
``\titleformat`` command to style the chapter titles.
.. versionchanged:: 1.5
formerly, use of *fncychap* with other styles than ``Bjarne`` was
dysfunctional.
- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
:file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
.. versionchanged:: 1.5
formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
options ``verbatimwithframe``, ``verbatimwrapslines``,
``verbatimsep``, ``verbatimborder``.
- the bibliography and Python Module index are typeset respectively within
environments ``sphinxthebibliography`` and ``sphinxtheindex``, which are
simple wrappers of the non-modified ``thebibliography`` and ``theindex``
@ -519,7 +463,20 @@ Let us now list some macros from the package file
.. versionchanged:: 1.5
formerly, the original environments were modified by Sphinx.
- the list is not exhaustive: refer to :file:`sphinx.sty` for more.
Miscellany
~~~~~~~~~~
- the section, subsection, ... headings are set using *titlesec*'s
``\titleformat`` command.
- for the ``'manual'`` docclass, the chapter headings can be customized using
*fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File
:file:`sphinx.sty` has custom re-definitions in case of *fncychap*
option ``Bjarne``.
.. versionchanged:: 1.5
formerly, use of *fncychap* with other styles than ``Bjarne`` was
dysfunctional.
- check file :file:`sphinx.sty` for more...
.. hint::