#!/usr/bin/env python3
#
# latex.py
r"""
Sphinx utilities for LaTeX builders.
.. versionadded:: 2.8.0
In addition to the developer API (see below), :mod:`sphinx_toolbox.latex`
configures Sphinx and LaTeX to correctly handle symbol footnotes.
.. versionchanged:: 2.12.0
Sphinx is also configured to respect ``.. only:: html`` etc. directives surrounding
toctree directives when determining the overall toctree depth.
.. extensions:: sphinx_toolbox.latex
.. latex:vspace:: -5px
Example Footnotes
--------------------
.. latex:vspace:: -10px
| Hello [1]_
| Goodbye [2]_
| Symbol [*]_
| Another Symbol [*]_
| Number Again [3]_
| Symbol 3 [*]_
| Symbol 4 [*]_
| Symbol 5 [*]_
| Symbol 6 [*]_
| Symbol 7 [*]_
| Symbol 8 [*]_
| Symbol 9 [*]_
.. latex:vspace:: 20px
.. [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:vspace:: -10px
.. rst:directive:: 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.
.. versionadded:: 2.9.0
.. rst:directive:: latex:clearpage
clearpage
Configures LaTeX to start a new page.
This directive has no effect with non-LaTeX builders.
.. versionadded:: 2.10.0
.. seealso:: :rst:dir:`latex:cleardoublepage`
.. rst:directive:: 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.
.. versionadded:: 2.10.0
.. seealso:: :rst:dir:`latex:clearpage`
.. rst:directive:: .. 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.
.. versionadded:: 2.11.0
.. latex:clearpage::
API Reference
----------------
.. latex:vspace:: -20px
"""
#
# Copyright © 2021 Dominic Davis-Foster <dominic@davis-foster.co.uk>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
# OR OTHER DEALINGS IN THE SOFTWARE.
#
# PatchedLaTeXBuilder based on Sphinx
# Copyright (c) 2007-2020 by the Sphinx team.
# | All rights reserved.
# |
# | Redistribution and use in source and binary forms, with or without
# | modification, are permitted provided that the following conditions are
# | met:
# |
# | * Redistributions of source code must retain the above copyright
# | notice, this list of conditions and the following disclaimer.
# |
# | * Redistributions in binary form must reproduce the above copyright
# | notice, this list of conditions and the following disclaimer in the
# | documentation and/or other materials provided with the distribution.
# |
# | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
# | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# | HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
# | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
# | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
# | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# stdlib
import re
from os.path import join as joinpath
from textwrap import dedent
from typing import Any, List, Optional, cast
# 3rd party
import sphinx
from docutils import nodes
from docutils.frontend import OptionParser
from docutils.transforms.references import Footnotes
from domdf_python_tools.paths import PathPlus
from domdf_python_tools.stringlist import DelimitedList
from sphinx import addnodes
from sphinx.application import Sphinx
from sphinx.builders.latex import LaTeXBuilder
from sphinx.domains import Domain
from sphinx.environment import BuildEnvironment
from sphinx.locale import __
from sphinx.util.docutils import SphinxDirective, SphinxFileOutput
from sphinx.util.nodes import process_only_nodes
from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter
# this package
from sphinx_toolbox.utils import Config, SphinxExtMetadata, metadata_add_version
try:
# 3rd party
from sphinx.util.display import progress_message
except ImportError:
# 3rd party
from sphinx.util import progress_message # type: ignore[no-redef]
_ = BuildEnvironment
__all__ = (
"use_package",
"visit_footnote",
"depart_footnote",
"SamepageDirective",
"ClearPageDirective",
"ClearDoublePageDirective",
"VSpaceDirective",
"LaTeXDomain",
"replace_unknown_unicode",
"better_header_layout",
"configure",
"setup",
)
footmisc_symbols = ['0', *Footnotes.symbols]
# footmisc_symbols = ['0', '*', '†', '‡', '§', '¶', '‖', "**", "††", "‡‡"]
[docs]def use_package(package: str, config: Config, *args: str, **kwargs: str) -> None:
r"""
Configure LaTeX to use the given package.
The ``\usepackage`` entry is added to the
:py:obj:`sphinx.config.Config.latex_elements` ``["preamble"]`` attribute.
:param package:
:param config:
:param \*args: Passed as options to the LaTeX package.
:param \*\*kwargs: Passed as named options to the LaTeX package.
"""
options: DelimitedList[str] = DelimitedList()
options.extend(args)
options.extend(map("{}={}".format, kwargs.items()))
use_string = rf"\usepackage[{options:,}]{{{package}}}"
if not hasattr(config, "latex_elements") or not config.latex_elements: # pragma: no cover
config.latex_elements = {}
latex_preamble = config.latex_elements.get("preamble", '')
if use_string not in latex_preamble:
config.latex_elements["preamble"] = f"{latex_preamble}\n{use_string}"
[docs]class SamepageDirective(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.
.. versionadded:: 2.9.0
"""
has_content = True
def run(self) -> List[nodes.Node]:
"""
Process the content of the directive.
"""
content_node = nodes.container(rawsource='\n'.join(self.content))
self.state.nested_parse(self.content, self.content_offset, content_node)
return [
nodes.raw('', r"\par\begin{samepage}", format="latex"),
content_node,
nodes.raw('', r"\end{samepage}\par", format="latex"),
]
[docs]class ClearPageDirective(SphinxDirective):
"""
Directive which configures LaTeX to start a new page.
This directive has no effect with non-LaTeX builders.
.. versionadded:: 2.10.0
.. seealso:: :class:`~.ClearDoublePageDirective`
"""
has_content = True
def run(self) -> List[nodes.Node]:
"""
Process the content of the directive.
"""
return [nodes.raw('', r"\clearpage", format="latex")]
[docs]class ClearDoublePageDirective(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.
.. versionadded:: 2.10.0
.. seealso:: :class:`~.ClearPageDirective`
"""
has_content = True
def run(self) -> List[nodes.Node]:
"""
Process the content of the directive.
"""
return [nodes.raw('', r"\cleardoublepage", format="latex")]
[docs]class VSpaceDirective(SphinxDirective):
"""
Directive which configures LaTeX to add or remove vertical space.
This directive has no effect with non-LaTeX builders.
.. versionadded:: 2.11.0
"""
required_arguments = 1 # the space
def run(self) -> List[nodes.Node]:
"""
Process the content of the directive.
"""
return [nodes.raw('', f"\n\\vspace{{{self.arguments[0]}}}\n", format="latex")]
[docs]class LaTeXDomain(Domain):
"""
Domain containing various LaTeX-specific directives.
.. versionadded:: 2.11.0
"""
name = "latex"
label = "LaTeX"
directives = {
"samepage": SamepageDirective,
"clearpage": ClearPageDirective,
"cleardoublepage": ClearDoublePageDirective,
"vspace": VSpaceDirective,
}
[docs]def replace_unknown_unicode(app: Sphinx, exception: Optional[Exception] = None) -> None:
r"""
Replaces certain unknown unicode characters in the Sphinx LaTeX output with the best equivalents.
.. only:: html
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 :event:`build-finished` event as follows:
.. code-block:: python
app.connect("build-finished", replace_unknown_unicode)
.. versionadded:: 2.9.0
:param app: The Sphinx application.
:param exception: Any exception which occurred and caused Sphinx to abort.
"""
if exception: # pragma: no cover
return
if app.builder is None or app.builder.name.lower() != "latex":
return
builder = cast(LaTeXBuilder, app.builder)
output_file = PathPlus(builder.outdir) / f"{builder.titles[0][1].lower()}.tex"
output_content = output_file.read_text()
output_content = output_content.replace('♠', r' $\spadesuit$ ')
output_content = output_content.replace('♥', r' $\heartsuit$ ')
output_content = output_content.replace('♦', r' $\diamondsuit$ ')
output_content = output_content.replace('♣', r' $\clubsuit$ ')
output_content = output_content.replace('\u200b', r'\hspace{0pt}') # Zero width space
output_content = output_content.replace('μ', r"\textmu{}")
output_content = output_content.replace('≡', r" $\equiv$ ")
output_content = output_content.replace('≈', r" $\approx$ ")
output_content = output_content.replace('≥', r" $\geq$ ")
output_content = output_content.replace('≤', r" $\leq$ ")
output_file.write_clean(output_content)
class PatchedLaTeXBuilder(LaTeXBuilder):
"""
Patched version of Sphinx's LaTeX builder which skips toctrees under ``.. only:: html`` etc. directives
when determining the max toctree depth.
The default behaviour uses the ``:maxdepth:`` option of the first toctree,
irrespective of whether the toctree will exist with the LaTeX builder.
""" # noqa: D400
# TODO: respect toctree caption for LaTeX table of contents too
# \addto\captionsenglish{\renewcommand{\contentsname}{Documentation}}
def write(self, *ignored: Any) -> None:
assert self.env is not None
docwriter = LaTeXWriter(self)
docsettings: Any = OptionParser(
defaults=self.env.settings,
components=(docwriter, ),
read_config_files=True,
).get_default_values()
if sphinx.version_info <= (4, 0):
# 3rd party
from sphinx.builders.latex import patch_settings # type: ignore[attr-defined]
patch_settings(docsettings)
self.init_document_data()
self.write_stylesheet()
for entry in self.document_data:
docname, targetname, title, author, themename = entry[:5]
theme = self.themes.get(themename)
toctree_only = False
if len(entry) > 5:
toctree_only = entry[5]
destination = SphinxFileOutput(
destination_path=joinpath(self.outdir, targetname),
encoding="utf-8",
overwrite_if_changed=True
)
with progress_message(__("processing %s") % targetname):
doctree = self.env.get_doctree(docname)
process_only_nodes(doctree, self.tags)
if hasattr(doctree, "findall"):
toctree = next(doctree.findall(addnodes.toctree), None)
else:
toctree = next(iter(doctree.traverse(addnodes.toctree)), None)
if toctree and toctree.get("maxdepth") > 0:
tocdepth = toctree.get("maxdepth")
else:
tocdepth = None
doctree = self.assemble_doctree(
docname,
toctree_only,
appendices=(self.config.latex_appendices if theme.name != "howto" else [])
)
doctree["docclass"] = theme.docclass
doctree["contentsname"] = self.get_contentsname(docname)
doctree["tocdepth"] = tocdepth
self.post_process_images(doctree)
self.update_doc_context(title, author, theme)
if hasattr(self, "update_context"): # pragma: no cover
# Only present in newer Sphinx versions
self.update_context()
with progress_message(__("writing")):
# pylint: disable=loop-invariant-statement
docsettings._author = author
docsettings._title = title
docsettings._contentsname = doctree["contentsname"]
docsettings._docname = docname
docsettings._docclass = theme.name
doctree.settings = docsettings
docwriter.theme = theme
docwriter.write(doctree, destination)
# pylint: enable=loop-invariant-statement
[docs]@metadata_add_version
def setup(app: Sphinx) -> SphinxExtMetadata:
"""
Setup :mod:`sphinx_toolbox.latex`.
.. versionadded:: 2.8.0
:param app: The Sphinx application.
"""
app.add_node(nodes.footnote, latex=(visit_footnote, depart_footnote), override=True)
app.add_directive("samepage", SamepageDirective)
app.add_directive("clearpage", ClearPageDirective)
app.add_directive("cleardoublepage", ClearDoublePageDirective)
app.add_domain(LaTeXDomain)
app.add_builder(PatchedLaTeXBuilder, override=True)
app.connect("config-inited", configure)
return {}