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 ♦
1

One

2

Two

*

Buckle my shoe

†

The second symbol

3

The number after the symbol

‡

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

  • **kwargs

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.

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

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

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.

class LaTeXDomain(env)[source]

Bases: Domain

Domain containing various LaTeX-specific directives.

New in version 2.11.0.

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.