def configure(app: Sphinx, config: Config):
"""
Configure :mod:`sphinx_toolbox.documentation_summary`.
:param app:
:param config:
"""
if not hasattr(config, "latex_elements"): # pragma: no cover
config.latex_elements = {} # type: ignore
latex_elements = (config.latex_elements or {})
latex_preamble = latex_elements.get("preamble", '')
summary = getattr(config, "documentation_summary", None)
if not summary:
return # pragma: no cover
summary_command = rf"\newcommand{{\thesummary}}{{{summary}}}"
if summary_command not in latex_preamble:
config.latex_elements["preamble"] = '\n'.join([
latex_preamble,
summary_command,
RENEW,
])
config.latex_elements["maketitle"] = '\n'.join(
[r"\sphinxmaketitle", RESET])
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:
:param \*\*kwargs:
"""
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 = {} # type: ignore
latex_preamble = config.latex_elements.get("preamble", '')
if use_string not in latex_preamble:
config.latex_elements["preamble"] = f"{latex_preamble}\n{use_string}"
def configure(app: Sphinx, config: Config):
"""
Configure :mod:`sphinx_toolbox.documentation_summary`.
:param app: The Sphinx application.
:param config:
"""
if not hasattr(config, "latex_elements"): # pragma: no cover
config.latex_elements = {} # type: ignore
latex_elements = (config.latex_elements or {})
latex_preamble = latex_elements.get("preamble", '')
summary = getattr(config, "documentation_summary", '').strip()
if not summary:
return # pragma: no cover
# Escape latex special characters
summary = summary.replace("~ ", r"\textasciitilde\space ")
summary = summary.replace("^ ", r"\textasciicircum\space ")
summary = summary.replace("\\ ", r"\textbackslash\space ")
summary = summary.translate({
35: r"\#",
36: r"\$",
37: r"\%",
38: r"\&",
94: r"\textasciicircum",
95: r"\_",
123: r"\{",
125: r"\}",
126: r"\textasciitilde",
})
# TODO: escape backslashes without breaking the LaTeX commands
summary_command = rf"\newcommand{{\thesummary}}{{{educateQuotes(summary)}}}"
if summary_command not in latex_preamble:
config.latex_elements["preamble"] = '\n'.join([
latex_preamble,
summary_command,
RENEW,
])
config.latex_elements["maketitle"] = '\n'.join([
config.latex_elements.get("maketitle", r"\sphinxmaketitle"),
RESET,
])
def configure(app: Sphinx, config: Config):
"""
Configure :mod:`sphinx_toolbox.tweaks.latex_toc`.
:param app:
:param config:
"""
if not hasattr(config, "latex_elements"):
config.latex_elements = {} # type: ignore
latex_preamble = (config.latex_elements or {}).get("preamble", '')
if use_bookmark not in latex_preamble:
config.latex_elements["preamble"] = f"{latex_preamble}\n{use_bookmark}"
def configure(app: Sphinx, config: Config):
"""
Configure Sphinx Extension.
:param app: The Sphinx application.
:param config:
"""
latex_elements = getattr(config, "latex_elements", {})
latex_extrapackages = StringList(latex_elements.get("extrapackages", ''))
latex_extrapackages.append(r"\usepackage{needspace}")
latex_elements["extrapackages"] = str(latex_extrapackages)
config.latex_elements = latex_elements # type: ignore
def configure(app: Sphinx, config: Config):
"""
Configure Sphinx Extension.
:param app: The Sphinx application.
:param config:
"""
if not hasattr(config, "latex_elements"): # pragma: no cover
config.latex_elements = {} # type: ignore
latex_elements = (config.latex_elements or {})
latex_preamble = latex_elements.get("preamble", '')
config.latex_elements["preamble"] = '\n'.join([
latex_preamble,
new_commands,
])
def configure(app: Sphinx, config: Config):
"""
Configure :mod:`sphinx_toolbox.code`.
.. versionadded:: 2.9.0
:param app: The Sphinx application.
:param config:
"""
latex_elements = getattr(config, "latex_elements", {})
latex_preamble = StringList(latex_elements.get("preamble", ''))
latex_preamble.blankline()
latex_preamble.append(r"\definecolor{nbsphinxin}{HTML}{307FC1}")
latex_preamble.append(r"\definecolor{nbsphinxout}{HTML}{BF5B3D}")
latex_elements["preamble"] = str(latex_preamble)
config.latex_elements = latex_elements # type: ignore
def configure(app: Sphinx, config: Config):
"""
Configure Sphinx Extension.
:param app: The Sphinx application.
:param config:
"""
if not hasattr(config, "latex_elements"): # pragma: no cover
config.latex_elements = {} # type: ignore
latex_elements = (config.latex_elements or {})
latex_preamble = latex_elements.get("preamble", '')
# Backported from Sphinx 4
# See https://github.com/sphinx-doc/sphinx/pull/8997
config.latex_elements["preamble"] = '\n'.join([
latex_preamble,
r"\makeatletter",
'',
r"\renewcommand{\py@sigparams}[2]{%",
r" \parbox[t]{\py@argswidth}{\raggedright #1\sphinxcode{)}#2\strut}%",
" % final strut is to help get correct vertical separation in case of multi-line",
" % box with the item contents.",
'}',
r"\makeatother",
])
config.latex_elements["hyperref"] = '\n'.join([
r"% Include hyperref last.",
r"\usepackage[pdfpagelabels,hyperindex,hyperfigures]{hyperref}",
r"% Fix anchor placement for figures with captions.",
r"\usepackage{hypcap}% it must be loaded after hyperref.",
])
config.latex_elements["maketitle"] = '\n'.join([
r"\begingroup", r"\let\oldthepage\thepage",
r"\renewcommand{\thepage}{T\oldthepage}",
config.latex_elements.get("maketitle",
r"\sphinxmaketitle"), r"\endgroup"
])
def configure(app: Sphinx, config: Config):
"""
Configure :mod:`sphinx_toolbox.latex`.
:param app: The Sphinx application.
:param config:
"""
if not hasattr(
config,
"latex_elements") or not config.latex_elements: # pragma: no cover
config.latex_elements = {} # type: ignore
latex_preamble = config.latex_elements.get("preamble", '')
command_string = r"\newcommand\thesymbolfootnote{\fnsymbol{footnote}}\let\thenumberfootnote\thefootnote"
if command_string not in latex_preamble:
config.latex_elements[
"preamble"] = f"{latex_preamble}\n{command_string}"
def better_header_layout(
config: Config,
space_before: int = 10,
space_after: int = 20,
) -> None:
"""
Makes LaTeX chapter names lowercase, and adjusts the spacing above and below the chapter name.
.. versionadded:: 2.10.0
:param config: The Sphinx configuration object.
:param space_before: The space, in pixels, before the chapter name.
:param space_after: The space, in pixels, after the chapter name.
"""
begin = "% begin st better header layout"
end = "% end st better header layout"
commands = rf"""
{begin}
\makeatletter
\renewcommand{{\DOCH}}{{%
\mghrulefill{{\RW}}\par\nobreak
\CNV\FmN{{\@chapapp}}\par\nobreak
\CNoV\TheAlphaChapter\par\nobreak
\vskip -1\baselineskip\vskip 5pt\mghrulefill{{\RW}}\par\nobreak
\vskip 10\p@
}}
\renewcommand{{\DOTI}}[1]{{%
\CTV\FmTi{{#1}}\par\nobreak
\vskip {space_before}\p@
}}
\renewcommand{{\DOTIS}}[1]{{%
\CTV\FmTi{{#1}}\par\nobreak
\vskip {space_after}\p@
}}
\makeatother
{end}
"""
if not hasattr(
config,
"latex_elements") or not config.latex_elements: # pragma: no cover
config.latex_elements = {} # type: ignore
latex_preamble = config.latex_elements.get("preamble", '')
if begin in latex_preamble:
config.latex_elements["preamble"] = re.sub(
f"{begin}.*{end}",
dedent(commands),
latex_preamble,
count=1,
flags=re.DOTALL,
)
else:
config.latex_elements[
"preamble"] = f"{latex_preamble}\n{dedent(commands)}"
config.latex_elements[
"fncychap"] = "\\usepackage[Bjarne]{fncychap}\n\\ChNameAsIs\n\\ChTitleAsIs\n"
