`latex`¶

Sphinx utilities for LaTeX builders.

New in version 2.8.0.

In addition to the developer API (see below), sphinx_toolbox.latex configures Sphinx and LaTeX to correctly handle symbol footnotes.

Changed in version 2.12.0: Sphinx is also configured to respect .. only:: html etc. directives surrounding toctree directives when determining the overall toctree depth.

Enable sphinx_toolbox.latex by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.latex',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Example Footnotes¶

Hello [1]
Goodbye [2]
Symbol [*]
Another Symbol [†]
Number Again [3]
Symbol 3 [‡]
Symbol 4 [§]
Symbol 5 [¶]
Symbol 6 [#]
Symbol 7 [♠]
Symbol 8 [♥]
Symbol 9 [♦]

Usage¶

.. latex:samepage::¶

.. samepage::¶

Configures LaTeX to make all content within this directive appear on the same page.

This can be useful to avoid awkward page breaks.

This directive has no effect with non-LaTeX builders.

New in version 2.9.0.

.. latex:clearpage::¶

.. clearpage::¶

Configures LaTeX to start a new page.

This directive has no effect with non-LaTeX builders.

New in version 2.10.0.

See also

latex:cleardoublepage

.. latex:cleardoublepage::¶

.. cleardoublepage::¶

Configures LaTeX to start a new page.

In a two-sided printing it also makes the next page a right-hand (odd-numbered) page, inserting a blank page if necessary.

This directive has no effect with non-LaTeX builders.

New in version 2.10.0.

See also

latex:clearpage

.. latex:vspace:: space¶

Configures LaTeX to add or remove vertical space.

The value for space is passed verbatim to the \vspace{} command. Ensure you pass a valid value.

This directive has no effect with non-LaTeX builders.

New in version 2.11.0.

API Reference¶

Functions:

`use_package`(package, config, args, *kwargs)	Configure LaTeX to use the given package.
`visit_footnote`(translator, node)	Visit a `docutils.nodes.footnote` node with the LaTeX translator.
`depart_footnote`(translator, node)	Depart a `docutils.nodes.footnote` node with the LaTeX translator.
`replace_unknown_unicode`(app[, exception])	Replaces certain unknown unicode characters in the Sphinx LaTeX output with the best equivalents.
`better_header_layout`(config[, space_before, ...])	Makes LaTeX chapter names lowercase, and adjusts the spacing above and below the chapter name.
`configure`(app, config)	Configure `sphinx_toolbox.latex`.
`setup`(app)	Setup `sphinx_toolbox.latex`.

Classes:

`SamepageDirective`(name, arguments, options, ...)	Directive which configures LaTeX to make all content within this directive appear on the same page.
`ClearPageDirective`(name, arguments, options, ...)	Directive which configures LaTeX to start a new page.
`ClearDoublePageDirective`(name, arguments, ...)	Directive which configures LaTeX to start a new page.
`VSpaceDirective`(name, arguments, options, ...)	Directive which configures LaTeX to add or remove vertical space.
`LaTeXDomain`(env)	Domain containing various LaTeX-specific directives.

use_package(package, config, *args, **kwargs)[source]¶

Configure LaTeX to use the given package.

The \usepackage entry is added to the sphinx.config.Config.latex_elements ["preamble"] attribute.

Parameters:

package (str)
config (Config)
*args (str) – Passed as options to the LaTeX package.
**kwargs (str) – Passed as named options to the LaTeX package.

visit_footnote(translator, node)[source]¶

Visit a docutils.nodes.footnote node with the LaTeX translator.

Unlike the default visit_footnote function, this one handles footnotes using symbols.

New in version 2.8.0.

Parameters:

translator (LaTeXTranslator)
node (footnote)

depart_footnote(translator, node)[source]¶

Depart a docutils.nodes.footnote node with the LaTeX translator.

New in version 2.8.0.

Parameters:

translator (LaTeXTranslator)
node (footnote)

class SamepageDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Directive which configures LaTeX to make all content within this directive appear on the same page.

This can be useful to avoid awkward page breaks.

This directive has no effect with non-LaTeX builders.

New in version 2.9.0.

has_content = True¶: Type: bool

class ClearPageDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Directive which configures LaTeX to start a new page.

This directive has no effect with non-LaTeX builders.

New in version 2.10.0.

See also

ClearDoublePageDirective

has_content = True¶: Type: bool

class ClearDoublePageDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Directive which configures LaTeX to start a new page.

In a two-sided printing it also makes the next page a right-hand (odd-numbered) page, inserting a blank page if necessary.

This directive has no effect with non-LaTeX builders.

New in version 2.10.0.

See also

ClearPageDirective

has_content = True¶: Type: bool

class VSpaceDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶

Bases: SphinxDirective

Directive which configures LaTeX to add or remove vertical space.

This directive has no effect with non-LaTeX builders.

New in version 2.11.0.

required_arguments = 1¶: Type: int

class LaTeXDomain(env)[source]¶

Bases: Domain

Domain containing various LaTeX-specific directives.

New in version 2.11.0.

name = 'latex'¶: Type: str

label = 'LaTeX'¶: Type: str

directives = {'cleardoublepage': <class 'sphinx_toolbox.latex.ClearDoublePageDirective'>, 'clearpage': <class 'sphinx_toolbox.latex.ClearPageDirective'>, 'samepage': <class 'sphinx_toolbox.latex.SamepageDirective'>, 'vspace': <class 'sphinx_toolbox.latex.VSpaceDirective'>}¶: Type: dict[str, type[Directive]]

data¶: Type: dict

replace_unknown_unicode(app, exception=None)[source]¶

Replaces certain unknown unicode characters in the Sphinx LaTeX output with the best equivalents.

The mapping is as follows:

♠ – spadesuit
♥ – heartsuit
♦ – diamondsuit
♣ – clubsuit
Zero width space – hspace{0pt}
μ – textmu
≡ – equiv (new in version 2.11.0)
≈ – approx (new in version 2.12.0)
≥ – geq (new in version 2.13.0)
≤ – leq (new in version 2.13.0)

This function can be hooked into the build-finished event as follows:

app.connect("build-finished", replace_unknown_unicode)

New in version 2.9.0.

Parameters:

app (Sphinx) – The Sphinx application.
exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

better_header_layout(config, space_before=10, space_after=20)[source]¶

Makes LaTeX chapter names lowercase, and adjusts the spacing above and below the chapter name.

New in version 2.10.0.

Parameters:

config (Config) – The Sphinx configuration object.
space_before (int) – The space, in pixels, before the chapter name. Default 10.
space_after (int) – The space, in pixels, after the chapter name. Default 20.

configure(app, config)[source]¶

Configure sphinx_toolbox.latex.

Parameters:

app (Sphinx) – The Sphinx application.
config (Config)

setup(app)[source]¶

Setup sphinx_toolbox.latex.

New in version 2.8.0.

Parameters:: app (Sphinx) – The Sphinx application.
Return type:: SphinxExtMetadata

Submodules¶

`sphinx_toolbox.latex.layout`¶

Makes minor adjustments to the LaTeX layout.

Increases the whitespace above function signatures by 5px, to prevent the function visually merging with the previous one.
Remove unnecessary indentation and allow “raggedright” for the fields in the body of functions, which prevents ugly whitespace and line breaks.
Disables justification for function signatures. This is a backport of changes from Sphinx 4 added in sphinx-doc/sphinx#8997.

New in version 2.12.0.
With Sphinx 3.5, doesn’t add \sphinxAtStartPar before every paragraph. The change in sphinx-doc/sphinx#8781 was to solve an issue with tables, but it isn’t clear why it then gets added for every paragraph so this extension removes it.

New in version 2.13.0.
Configures hyperref to apply correct page numbering to the frontmatter.

New in version 2.14.0.
Optionally, configures the needspace package.

The needspace_amount option can be set in conf.py to add the \needspace{} command before each addnodes.desc node (i.e. a function or class description). The amount of space is set by the needspace_amount option, e.g.:
```
needspace_amount = r"4\baselineskip"
```
New in version 3.0.0.

needspace_amount¶

Type: str

Default: None

Sets the value for the \needspace{} command.

Values should be in the form r"4\baselineskip".

New in version 3.0.0.

New in version 2.10.0.

Changed in version 3.0.0: Moved from sphinx_toolbox.tweaks.latex_layout.

Enable sphinx_toolbox.latex.layout by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.latex.layout',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

setup(app)[source]¶

Setup sphinx_toolbox.latex.layout.

Parameters:: app (Sphinx) – The Sphinx application.
Return type:: SphinxExtMetadata

`sphinx_toolbox.latex.succinct_seealso`¶

Sphinx extension which customises seealso directives to be on one line with the LaTeX builder.

Enable sphinx_toolbox.latex.succinct_seealso by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.latex.succinct_seealso',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

New in version 3.0.0.

setup(app)[source]¶

Setup sphinx_toolbox.latex.succinct_seealso.

Parameters:: app (Sphinx) – The Sphinx application.
Return type:: SphinxExtMetadata

`sphinx_toolbox.latex.toc`¶

Adjusts the default LaTeX output as follows:

The captions from toctree directives are converted into document parts.
The PDF outline has the correct hierarchy, including having the indices as top-level elements.

New in version 2.1.0.

Changed in version 3.0.0: Moved from sphinx_toolbox.tweaks.latex_toc.

Enable sphinx_toolbox.latex.toc by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.latex.toc',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

setup(app)[source]¶

Setup sphinx_toolbox.tweaks.latex_toc.

Parameters:: app (Sphinx) – The Sphinx application.
Return type:: SphinxExtMetadata

latex¶

Example Footnotes¶

Usage¶

API Reference¶

Submodules¶

sphinx_toolbox.latex.layout¶

sphinx_toolbox.latex.succinct_seealso¶

sphinx_toolbox.latex.toc¶

`latex`¶

`sphinx_toolbox.latex.layout`¶

`sphinx_toolbox.latex.succinct_seealso`¶

`sphinx_toolbox.latex.toc`¶