From 4c7fe10a4b192846f8e2a3c7d032cea53111909b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Sat, 17 Aug 2024 20:33:15 +0200 Subject: [PATCH 01/12] LaTeX: fix mark-up when \DUrole is used with multiple classes (#12745) --- CHANGES.rst | 4 ++++ doc/latex.rst | 13 +++++++++++++ sphinx/writers/latex.py | 4 ++-- .../expects/longtable_having_widths.tex | 2 +- .../expects/table_having_widths.tex | 2 +- tests/test_builders/test_build_latex.py | 3 ++- tests/test_directives/test_directive_code.py | 8 ++++---- 7 files changed, 27 insertions(+), 9 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 7de6ab68dfe..61a79bf9966 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -62,6 +62,10 @@ Bugs fixed get passed to :program:`latexmk`. Let :option:`-Q ` (silent) apply as well to the PDF build phase. Patch by Jean-François B. +* #12744: LaTeX: Classes injected by a custom interpreted text role now give + rise to nested ``\DUrole``'s, rather than a single one with comma separated + classes. + Patch by Jean-François B. * #11970, #12551: singlehtml builder: make target URIs to be same-document references in the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`, e.g., ``index.html#foo`` becomes ``#foo``. diff --git a/doc/latex.rst b/doc/latex.rst index 821c8329764..0f9e77d4540 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1865,6 +1865,19 @@ Miscellany Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. +- The :dudir:`role` directive allows to mark inline text with class arguments. + This is handled in LaTeX output via the ``\DUrole`` dispatcher command `as + in Docutils `_. Object signatures also use ``\DUrole`` for + some components, with one or two-letters class names as in HTML output. + + .. versionchanged:: 8.1.0 + When multiple classes are injected via a a custom role, the LaTeX output + uses nested ``\DUrole``'s as in the `Docutils documentation + `_. Formerly it used a single ``\DUrole`` with comma + separated classes, making the LaTeX customization more arduous. + +.. _classarguments: https://docutils.sourceforge.io/docs/user/latex.html#custom-interpreted-text-roles + .. _latexcontainer: - Docutils :dudir:`container` directives are supported in LaTeX output: to diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 4badfa87f85..4fb271d8537 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -2173,8 +2173,8 @@ def visit_inline(self, node: Element) -> None: self.body.append(r'\sphinxaccelerator{') self.context.append('}') elif classes and not self.in_title: - self.body.append(r'\DUrole{%s}{' % ','.join(classes)) - self.context.append('}') + self.body.append(r'\DUrole{' + r'}{\DUrole{'.join(classes) + '}{') + self.context.append('}' * len(classes)) else: self.context.append('') diff --git a/tests/roots/test-latex-table/expects/longtable_having_widths.tex b/tests/roots/test-latex-table/expects/longtable_having_widths.tex index 24dad79fd6a..bcad23be4f0 100644 --- a/tests/roots/test-latex-table/expects/longtable_having_widths.tex +++ b/tests/roots/test-latex-table/expects/longtable_having_widths.tex @@ -70,4 +70,4 @@ \end{savenotes} \sphinxAtStartPar -See {\hyperref[\detokenize{longtable:mylongtable}]{\sphinxcrossref{mylongtable}}}, same as {\hyperref[\detokenize{longtable:namedlongtable}]{\sphinxcrossref{\DUrole{std,std-ref}{this one}}}}. +See {\hyperref[\detokenize{longtable:mylongtable}]{\sphinxcrossref{mylongtable}}}, same as {\hyperref[\detokenize{longtable:namedlongtable}]{\sphinxcrossref{\DUrole{std}{\DUrole{std-ref}{this one}}}}}. diff --git a/tests/roots/test-latex-table/expects/table_having_widths.tex b/tests/roots/test-latex-table/expects/table_having_widths.tex index fe5f4c44d72..e9863d277f6 100644 --- a/tests/roots/test-latex-table/expects/table_having_widths.tex +++ b/tests/roots/test-latex-table/expects/table_having_widths.tex @@ -43,4 +43,4 @@ \sphinxattableend\end{savenotes} \sphinxAtStartPar -See {\hyperref[\detokenize{tabular:mytabular}]{\sphinxcrossref{\DUrole{std,std-ref}{this}}}}, same as {\hyperref[\detokenize{tabular:namedtabular}]{\sphinxcrossref{namedtabular}}}. +See {\hyperref[\detokenize{tabular:mytabular}]{\sphinxcrossref{\DUrole{std}{\DUrole{std-ref}{this}}}}}, same as {\hyperref[\detokenize{tabular:namedtabular}]{\sphinxcrossref{namedtabular}}}. diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 13c33224080..75073176588 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -1016,7 +1016,8 @@ def test_reference_in_caption_and_codeblock_in_footnote(app): assert ( 'This is a reference to the code\\sphinxhyphen{}block in the footnote:\n' '{\\hyperref[\\detokenize{index:codeblockinfootnote}]' - '{\\sphinxcrossref{\\DUrole{std,std-ref}{I am in a footnote}}}}' + '{\\sphinxcrossref{\\DUrole{std}{\\DUrole{std-ref}' + '{I am in a footnote}}}}}' ) in result assert ( '&\n\\sphinxAtStartPar\nThis is one more footnote with some code in it %\n' diff --git a/tests/test_directives/test_directive_code.py b/tests/test_directives/test_directive_code.py index 13b49e2af57..65e16b805bd 100644 --- a/tests/test_directives/test_directive_code.py +++ b/tests/test_directives/test_directive_code.py @@ -333,7 +333,7 @@ def test_code_block_namedlink_latex(app): ) link1 = ( '\\hyperref[\\detokenize{caption:name-test-rb}]' - '{\\sphinxcrossref{\\DUrole{std,std-ref}{Ruby}}' + '{\\sphinxcrossref{\\DUrole{std}{\\DUrole{std-ref}{Ruby}}}}' ) label2 = ( '\\def\\sphinxLiteralBlockLabel' @@ -341,7 +341,7 @@ def test_code_block_namedlink_latex(app): ) link2 = ( '\\hyperref[\\detokenize{namedblocks:some-ruby-code}]' - '{\\sphinxcrossref{\\DUrole{std,std-ref}{the ruby code}}}' + '{\\sphinxcrossref{\\DUrole{std}{\\DUrole{std-ref}{the ruby code}}}}' ) assert label1 in latex assert link1 in latex @@ -472,7 +472,7 @@ def test_literalinclude_namedlink_latex(app): ) link1 = ( '\\hyperref[\\detokenize{caption:name-test-py}]' - '{\\sphinxcrossref{\\DUrole{std,std-ref}{Python}}' + '{\\sphinxcrossref{\\DUrole{std}{\\DUrole{std-ref}{Python}}}}' ) label2 = ( '\\def\\sphinxLiteralBlockLabel' @@ -480,7 +480,7 @@ def test_literalinclude_namedlink_latex(app): ) link2 = ( '\\hyperref[\\detokenize{namedblocks:some-python-code}]' - '{\\sphinxcrossref{\\DUrole{std,std-ref}{the python code}}}' + '{\\sphinxcrossref{\\DUrole{std}{\\DUrole{std-ref}{the python code}}}}' ) assert label1 in latex assert link1 in latex From 67aed4194082de346a07a79158c6a822e2ea4bbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Sat, 17 Aug 2024 20:59:24 +0200 Subject: [PATCH 02/12] LaTeX: avoid "Overfull \hbox" reports when solved by verbatimforcewraps (#12733) --- CHANGES.rst | 4 ++++ sphinx/texinputs/sphinxlatexliterals.sty | 3 +++ 2 files changed, 7 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 61a79bf9966..881c642512e 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -45,6 +45,10 @@ Bugs fixed * #12514: intersphinx: fix the meaning of a negative value for :confval:`intersphinx_cache_limit`. Patch by Shengyu Zhang. +* #12722: LaTeX: avoid TeX reporting ``Overfull \hbox`` from too long + strings in a codeline when the problem has actually been solved thanks + to :ref:`latexsphinxsetupforcewraps`. + Patch by Jean-François B. * #12730: The ``UnreferencedFootnotesDetector`` transform has been improved to more consistently detect unreferenced footnotes. Note, the priority of the transform has been changed from 200 to 622, diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty index c2c0806455d..11991d9c3e8 100644 --- a/sphinx/texinputs/sphinxlatexliterals.sty +++ b/sphinx/texinputs/sphinxlatexliterals.sty @@ -512,6 +512,9 @@ \setbox\spx@tempboxa \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@ \doublehyphendemerits\z@\finalhyphendemerits\z@ +% Avoid TeX reporting Overfull \hbox'es during this measuring phase. Setting +% \hbadness to \@M to avoid Underfull reports is unneeded due to \raggedright. + \hfuzz\maxdimen \spx@everypar{}\noindent\strut\FV@Line\strut\spx@par \spx@verb@getwidths}% \ifdim\spx@verb@maxwidth> From 1fc780cd781bc71ac71bad1078c09ab71e0949a0 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 18 Aug 2024 02:10:57 +0100 Subject: [PATCH 03/12] Test on free-threaded builds of Python (#12798) --- .github/workflows/main.yml | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 7d3f5608551..d4018b5f50a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -102,6 +102,43 @@ jobs: env: PYTHONWARNINGS: "error" # treat all warnings as errors + deadsnakes-free-threraded: + runs-on: ubuntu-latest + name: Python ${{ matrix.python }} (Docutils ${{ matrix.docutils }}; free-threaded) + strategy: + fail-fast: false + matrix: + python: + - "3.13-dev" + docutils: + - "0.20" + - "0.21" + + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python }} (deadsnakes) + uses: deadsnakes/action@v3.1.0 + with: + python-version: ${{ matrix.python }} + nogil: true + - name: Check Python version + run: python --version --version + - name: Install graphviz + run: sudo apt-get install graphviz + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install .[test] + - name: Install Docutils ${{ matrix.docutils }} + run: python -m pip install --upgrade "docutils~=${{ matrix.docutils }}.0" + # markupsafe._speedups has not declared that it can run safely without the GIL + - name: Remove markupsafe._speedups + run: rm -rf "$(python -c 'from markupsafe._speedups import __file__ as f; print(f)')" + - name: Test with pytest + run: python -m pytest -vv --durations 25 + env: + PYTHONWARNINGS: "error" # treat all warnings as errors + windows: runs-on: windows-2019 name: Windows From e0f200934683a1356440218060235c259a5247d8 Mon Sep 17 00:00:00 2001 From: Thomas Fanning Date: Sun, 18 Aug 2024 14:34:20 -0500 Subject: [PATCH 04/12] LaTeX: Add `math_numsep` support to latex builder (#12652) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jean-François B <2589111+jfbu@users.noreply.github.com> --- CHANGES.rst | 2 ++ doc/latex.rst | 7 ++++++ sphinx/texinputs/sphinx.sty | 5 ++-- sphinx/texinputs/sphinxlatexnumfig.sty | 31 ++++++++++++++++++------- sphinx/writers/latex.py | 5 +++- tests/test_builders/test_build_latex.py | 10 ++++---- 6 files changed, 43 insertions(+), 17 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 881c642512e..44fcb99403c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -30,6 +30,8 @@ Features added output files. * #12474: Support type-dependent search result highlighting via CSS. Patch by Tim Hoffmann. +* #12652: LaTeX: Add :confval:`math_numsep` support to latex builder. + Patch by Thomas Fanning and Jean-François B. * #12743: No longer exit on the first warning when :option:`--fail-on-warning ` is used. Instead, exit with a non-zero status if any warnings were generated diff --git a/doc/latex.rst b/doc/latex.rst index 0f9e77d4540..2e0baef1f38 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -690,6 +690,13 @@ The color used in the above example is available from having passed the .. versionadded:: 1.5.3 +``mathnumsep`` + This defaults to the string (without quotes!) as set by + :confval:`math_numsep` (which itself defaults to ``'.'``). Use it if + a different setting is needed for LaTeX output. + + .. versionadded:: 8.1.0 + ``verbatimwithframe`` Boolean to specify if :rst:dir:`code-block`\ s and literal includes are framed. Setting it to ``false`` does not deactivate use of package diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index e6c96340fe3..5c5f2f7a606 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -156,6 +156,7 @@ \DeclareStringOption[-1]{numfigreset} \DeclareBoolOption[false]{nonumfigreset} \DeclareBoolOption[false]{mathnumfig} +\DeclareStringOption[.]{mathnumsep} \define@key{sphinx}{bookmarksdepth}{\AtBeginDocument{\hypersetup{bookmarksdepth=#1}}} \AtBeginDocument{\define@key{sphinx}{bookmarksdepth}{\hypersetup{bookmarksdepth=#1}}} % \DeclareBoolOption[false]{usespart}% not used @@ -731,7 +732,7 @@ \spx@tempa{div.important_} {important} \spx@tempa{div.tip_} {tip} - % Add "legacy" hintTeXextras etc... + % Add "legacy" hintTeXextras etc... \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix \expandafter\let\csname KV@sphinx@#2TeXextras\expandafter\endcsname \csname KV@sphinx@#1TeXextras\endcsname @@ -807,7 +808,7 @@ % We try to % - get Sphinx PDF builds to process fine in absence of fontawesome5 % - use fontawesome5 if present, but not if user prefers another package -% - provide an interface for using other LaTeX code for icons +% - provide an interface for using other LaTeX code for icons % - provide an interface for using some other package than fontawesome5 % Indeed we can't load fontawesome5 unconditionally even if available, % as it proves incompatible with fontawesome package. diff --git a/sphinx/texinputs/sphinxlatexnumfig.sty b/sphinx/texinputs/sphinxlatexnumfig.sty index 95fdddf7ce4..22fcbb03900 100644 --- a/sphinx/texinputs/sphinxlatexnumfig.sty +++ b/sphinx/texinputs/sphinxlatexnumfig.sty @@ -1,7 +1,7 @@ %% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS % % change this info string if making any custom modification -\ProvidesPackage{sphinxlatexnumfig}[2021/01/27 numbering] +\ProvidesPackage{sphinxlatexnumfig}[2024/07/31 v8.1.0 numbering] % Requires: remreset (old LaTeX only) % relates to numfig and numfig_secnum_depth configuration variables @@ -37,7 +37,11 @@ \def\theequation{\arabic{equation}}% \fi \else -\let\spx@preAthefigure\@empty +% See apologetic comments on TeX wizardry at bottom of file. +% The reason for this one is to catch case where there will be only +% the number with no prefix from enclosing sectioning (can happen +% with latex_toplevel_sectioning='part'). +\def\spx@preAthefigure{\expandafter\spx@magicsep@s\romannumeral-`0} \let\spx@preBthefigure\@empty % \ifspx@opt@usespart % <-- LaTeX writer could pass such a 'usespart' boolean % % as sphinx.sty package option @@ -51,7 +55,7 @@ \ifnum\spx@opt@numfigreset>0 \ltx@ifundefined{c@chapter} {} - {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}.}% + {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}}% \fi \ifnum\spx@opt@numfigreset>1 @@ -61,7 +65,7 @@ \ifspx@opt@mathnumfig \@addtoreset{equation}{section}% \fi% - \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}.}% + \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}% \fi \ifnum\spx@opt@numfigreset>2 @@ -71,7 +75,7 @@ \ifspx@opt@mathnumfig \@addtoreset{equation}{subsection}% \fi% - \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}.}% + \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}% \fi \ifnum\spx@opt@numfigreset>3 @@ -81,7 +85,7 @@ \ifspx@opt@mathnumfig \@addtoreset{equation}{subsubsection}% \fi% - \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}.}% + \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}% \fi \ifnum\spx@opt@numfigreset>4 @@ -91,7 +95,7 @@ \ifspx@opt@mathnumfig \@addtoreset{equation}{paragraph}% \fi% - \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}.}% + \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}% \fi \ifnum\spx@opt@numfigreset>5 @@ -101,7 +105,7 @@ \ifspx@opt@mathnumfig \@addtoreset{equation}{subparagraph}% \fi% - \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}.}% + \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}\spx@magicsep}% \g@addto@macro\spx@preBthefigure{\fi}% \fi \expandafter\g@addto@macro @@ -114,9 +118,18 @@ \g@addto@macro\theliteralblock{\arabic{literalblock}}% \ifspx@opt@mathnumfig \let\theequation\spx@preAthefigure - \g@addto@macro\theequation{\arabic{equation}}% + \g@addto@macro\theequation{E}% \fi \fi }% end of big \AtBeginDocument +% Sorry for TeX wizardry here. We need to keep expandability. Explaining +% the mechanism is not really feasible to non TeX-experts, but the idea +% is to force next `\ifnum` conditional so we can check what comes next. +% All cases are accounted for (i.e. not an equation, or an equation at top +% level, or an equation in some section at some depth). +\def\spx@magicsep{\expandafter\spx@magicsep@i\romannumeral-`0} +\def\spx@magicsep@i#1{\if#1E\spx@opt@mathnumsep\arabic{equation}\else.#1\fi} +% +\def\spx@magicsep@s#1{\if#1E\arabic{equation}\else#1\fi} \endinput diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 4fb271d8537..daee856f918 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -355,7 +355,10 @@ def __init__(self, document: nodes.document, builder: LaTeXBuilder, sphinxpkgoptions.append('nonumfigreset') if self.config.numfig and self.config.math_numfig: - sphinxpkgoptions.append('mathnumfig') + sphinxpkgoptions.extend([ + 'mathnumfig', + 'mathnumsep={%s}' % self.config.math_numsep, + ]) if (self.config.language not in {'en', 'ja'} and 'fncychap' not in self.config.latex_elements): diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 75073176588..1d474f67691 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -659,25 +659,25 @@ def test_latex_obey_numfig_secnum_depth_is_zero(app): app.build(force_all=True) result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') - assert '\\usepackage[,nonumfigreset,mathnumfig]{sphinx}' in result + assert '\\usepackage[,nonumfigreset,mathnumfig,mathnumsep={.}]{sphinx}' in result result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') - assert '\\usepackage[,nonumfigreset,mathnumfig]{sphinx}' in result + assert '\\usepackage[,nonumfigreset,mathnumfig,mathnumsep={.}]{sphinx}' in result @pytest.mark.sphinx( 'latex', testroot='latex-numfig', - confoverrides={'numfig': True, 'numfig_secnum_depth': 2}, + confoverrides={'numfig': True, 'numfig_secnum_depth': 2, 'math_numsep': '-'}, ) def test_latex_obey_numfig_secnum_depth_is_two(app): app.build(force_all=True) result = (app.outdir / 'SphinxManual.tex').read_text(encoding='utf8') - assert '\\usepackage[,numfigreset=2,mathnumfig]{sphinx}' in result + assert '\\usepackage[,numfigreset=2,mathnumfig,mathnumsep={-}]{sphinx}' in result result = (app.outdir / 'SphinxHowTo.tex').read_text(encoding='utf8') - assert '\\usepackage[,numfigreset=3,mathnumfig]{sphinx}' in result + assert '\\usepackage[,numfigreset=3,mathnumfig,mathnumsep={-}]{sphinx}' in result @pytest.mark.sphinx( From 0504903d47b70afd1e89d4e5a15ae131156c7569 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 09:11:14 +0200 Subject: [PATCH 05/12] Update changes/7.4.rst to quote fix of #8807 (#12802) --- doc/changes/7.4.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/changes/7.4.rst b/doc/changes/7.4.rst index 94a4e85ce1f..0729385a79a 100644 --- a/doc/changes/7.4.rst +++ b/doc/changes/7.4.rst @@ -217,7 +217,8 @@ Bugs fixed * #12410: LaTeX: for French and ``'lualatex'`` as :confval:`latex_engine` use ``babel`` as with ``'xelatex'`` (and not ``polyglossia``). Patch by Jean-François B. -* #12520: LaTeX: let :rst:dir:`todolist` produce correct hyperlinks in PDF. +* #8807, #12520: LaTeX: let :rst:dir:`todolist` produce correct hyperlinks + in PDF. Patch by Jean-François B. * #12416: Ensure that configuration setting aliases are always synchronised when one value or the other is modified. From 48a85797869944021467f29022a7ece1527e6ec2 Mon Sep 17 00:00:00 2001 From: Shengyu Zhang Date: Tue, 20 Aug 2024 00:17:15 +0800 Subject: [PATCH 06/12] docs: fix docstring of index domain (#12804) --- sphinx/domains/index.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/domains/index.py b/sphinx/domains/index.py index 87d1cacbd6b..67cc4050a36 100644 --- a/sphinx/domains/index.py +++ b/sphinx/domains/index.py @@ -28,7 +28,7 @@ class IndexDomain(Domain): - """Mathematics domain.""" + """Index domain.""" name = 'index' label = 'index' From 1c131dfffe2d359eda93f7d4cc6d920fbe76efe4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 20:43:47 +0200 Subject: [PATCH 07/12] LaTeX: make contents, topic, and sidebar separately customizable (#12704) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- CHANGES.rst | 6 + doc/latex.rst | 212 ++++++++++-------- sphinx/texinputs/sphinx.sty | 111 +++++++-- sphinx/texinputs/sphinxlatexadmonitions.sty | 86 ++++--- sphinx/texinputs/sphinxlatexshadowbox.sty | 82 ++++++- sphinx/texinputs/sphinxlatexstyletext.sty | 6 +- sphinx/writers/latex.py | 24 +- .../test-latex-contents-topic-sidebar/conf.py | 0 .../index.rst | 19 ++ tests/roots/test-root/conf.py | 13 +- tests/test_builders/test_build_latex.py | 27 +++ 11 files changed, 410 insertions(+), 176 deletions(-) create mode 100644 tests/roots/test-latex-contents-topic-sidebar/conf.py create mode 100644 tests/roots/test-latex-contents-topic-sidebar/index.rst diff --git a/CHANGES.rst b/CHANGES.rst index 44fcb99403c..3f0ce6e7ba0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -28,6 +28,9 @@ Features added * #11328: Mention evaluation of templated content during production of static output files. +* #12704: LaTeX: make :dudir:`contents `, :dudir:`topic`, + and :dudir:`sidebar` directives separately customizable for PDF output. + Patch by Jean-François B. and Bénédikt Tran. * #12474: Support type-dependent search result highlighting via CSS. Patch by Tim Hoffmann. * #12652: LaTeX: Add :confval:`math_numsep` support to latex builder. @@ -56,6 +59,9 @@ Bugs fixed Note, the priority of the transform has been changed from 200 to 622, so that it now runs after the docutils ``Footnotes`` resolution transform. Patch by Chris Sewell. +* #12778: LaTeX: let :ref:`'sphinxsetup' ` + ``div.topic_box-shadow`` key if used with only one dimension set both + x-offset and y-offset as per documentation. * #12587: Do not warn when potential ambiguity detected during Intersphinx resolution occurs due to duplicate targets that differ case-insensitively. Patch by James Addison. diff --git a/doc/latex.rst b/doc/latex.rst index 2e0baef1f38..5c9c503565b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -947,32 +947,24 @@ The color used in the above example is available from having passed the Default: ``\fboxrule`` -``shadowsep`` - The separation between contents and frame for contents_ and - :dudir:`topic` boxes. +.. important:: - See :ref:`additionalcss` for the alias ``div.topic_padding``. + Since 8.1.0 it is possible to style separately the :dudir:`topic`, + contents_, and :dudir:`sidebar` directives, and their defaults differ. + See :ref:`additionalcss`. The next three keys are kept as legacy + interface not distinguishing between the three directives. - Default: ``5pt`` +``shadowsep`` + This legacy option sets the padding (same in all directions) simultaneously + for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. ``shadowsize`` - The width of the lateral "shadow" to the right and bottom. - - See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to - configure separately the widths of the vertical and horizontal shadows. - - Default: ``4pt`` - - .. versionchanged:: 6.1.2 - Fixed a regression introduced at ``5.1.0`` which modified unintentionally - the width of topic boxes and worse had made usage of this key break PDF - builds. + This legacy option sets the shadow width simultaneously for the + :dudir:`topic`, contents_, and :dudir:`sidebar` directives. ``shadowrule`` - The width of the frame around :dudir:`topic` boxes. See also - :ref:`additionalcss` for ``div.topic_border-width``. - - Default: ``\fboxrule`` + This legacy option sets the border-width (same on all sides) simultaneously + for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. .. important:: @@ -1155,6 +1147,13 @@ Additional CSS-like ``'sphinxsetup'`` keys set the foreground and background colors for the title as well as the LaTeX code for the icon. +.. versionadded:: 7.4.0 + Customizability of the :rst:dir:`seealso` and + :rst:dir:`todo` directives. + +.. versionadded:: 8.1.0 + Separate customizability and new defaults for the + :dudir:`topic`, contents_, and :dudir:`sidebar` directives. Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used @@ -1205,18 +1204,16 @@ which is then followed by an underscore, then the property name. :header: Directive, Option prefix, LaTeX environment :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim`` - :dudir:`topic`, ``div.topic``, ``sphinxShadowBox`` - contents_, ``div.topic``, ``sphinxShadowBox`` + :rst:dir:`literalinclude`, ``pre``, ``sphinxVerbatim`` + :dudir:`topic`, ``div.topic``, ``sphinxtopic`` + contents_, ``div.contents``, ``sphinxcontents`` + :dudir:`sidebar`, ``div.sidebar``, ``sphinxsidebar`` :dudir:`note`, ``div.note``, ``sphinxnote`` :dudir:`warning`, ``div.warning``, ``sphinxwarning`` further admonition types ````, ``div.``, ``sphinx`` :rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso`` :rst:dir:`todo`, ``div.todo``, ``sphinxtodo`` - -.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and - :rst:dir:`todo` directives. - Here are now these options as well as their common defaults. Replace below ```` by the actual prefix as explained above. Don't forget the underscore separating the prefix from the property names. @@ -1231,16 +1228,19 @@ forget the underscore separating the prefix from the property names. The default is that all those dimensions are equal. They are set to: * ``0.4pt`` for :rst:dir:`code-block`, - * ``0.5pt`` for :dudir:`topic` or contents_ directive, + * ``0.5pt`` for :dudir:`topic` and contents_ directive, + * ``1pt`` for :dudir:`sidebar` directive, * ``0.5pt`` for :dudir:`note` and other "light" admonitions, * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, * ``1pt`` for :dudir:`warning` and other "strong" admonitions except :dudir:`error` which uses ``1.25pt``. .. versionchanged:: 7.4.0 - Changed defaults for :dudir:`topic` and :dudir:`error`. + .. versionchanged:: 8.1.0 + Distinct from :dudir:`topic` defaults for :dudir:`sidebar`. + - ``_box-decoration-break`` can be set to either ``clone`` or ``slice`` and configures the behavior at page breaks. It defaults to ``slice`` for :rst:dir:`code-block` (i.e. for ``=pre``) @@ -1255,8 +1255,9 @@ forget the underscore separating the prefix from the property names. The defaults: * all four ``3pt`` for :rst:dir:`code-block`, - * ``10pt``, ``7pt``, ``12pt``, ``7pt`` for :dudir:`topic` or - contents_ directive, + * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for :dudir:`topic`, + * ``10pt``, ``7pt``, ``12pt``, ``7pt`` for contents_, + * ``6pt``, ``5.5pt``, ``6pt``, ``5.5pt`` for :dudir:`sidebar`, * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for all "light" admonitions as well as the :rst:dir:`seealso` and :rst:dir:`todo` directives. * ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types @@ -1270,6 +1271,9 @@ forget the underscore separating the prefix from the property names. vertically across admonition types on same page in PDF. This is only a property of defaults, not a constraint on possible user choices. + .. versionchanged:: 8.1.0 + Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. + - | ``_border-top-left-radius``, | ``_border-top-right-radius``, | ``_border-bottom-right-radius``, @@ -1281,16 +1285,20 @@ forget the underscore separating the prefix from the property names. The defaults: * ``3pt`` for :rst:dir:`code-block` (since 6.0.0) and all corners, - * ``12pt`` for the bottom right corner of :dudir:`topic`, other corners are - straight, + * ``8pt`` for all corners of :dudir:`topic`, + * ``12pt`` for the bottom right corner of contents_, others use ``0pt``, + * ``12pt`` for the top-left and bottom-right corners for :dudir:`sidebar`, + ``0pt`` for top-right and bottom-left. * all radii set to ``5pt`` for :dudir:`note`, :dudir:`hint` and :dudir:`tip`, * ``0pt``, i.e. straight corners for all other directives. .. versionchanged:: 7.4.0 + :dudir:`topic` and :dudir:`note`\ -like + admonitions acquire (at least one) rounded corners. - :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) - rounded corners. + .. versionchanged:: 8.1.0 + Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. See a remark above about traps with spaces in LaTeX. - ``_box-shadow`` is special in so far as it may be: @@ -1300,11 +1308,16 @@ forget the underscore separating the prefix from the property names. * or two dimensions (separated by a space), * or two dimensions followed by the keyword ``inset``. - The x-offset and y-offset may be negative. The default is ``none``, - *except* for the :dudir:`topic` or contents_ directives, for which it is - ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right - and below the frame. The lateral shadow then extends into the page right - margin. + The x-offset and y-offset may be negative. A negative x-offset means + that the shadow is on the left. The shadow extends into the page margin, + whether the offset is positive or negative. + + The default is ``none`` *except* for the contents_ directive which uses + ``4pt 4pt``. + + .. versionchanged:: 8.1.0 + No shadow per default for :dudir:`topic` and :dudir:`sidebar`. + - | ``_border-TeXcolor``, | ``_background-TeXcolor``, | ``_box-shadow-TeXcolor``, @@ -1321,14 +1334,14 @@ forget the underscore separating the prefix from the property names. - ``{HTML}{F7F7F7}`` serves as background color to all. - ``{HTML}{86989B}`` is border color of light admonitions (inclusive of - :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic` and - contents_ directives. - - ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions, + :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic`, + contents_ and :dudir:`sidebar` directives. + - ``{HTML}{940000}`` is border color of :dudir:`warning`-type admonitions, except :dudir:`error` which uses ``{HTML}{B40000}``. - The only directives displaying a shadow per default are :dudir:`topic` and - contents_ (handled identically at LaTeX level) and their shadow color is - ``{HTML}{6C6C6C}``. For all others the default shadow color is black. + The only directives displaying a shadow per default are contents_ and + :dudir:`sidebar`. The shadow-color for the former is ``{HTML}{6C6C6C}`` + and for the latter ``{HTML}{9EACAF}``. The ``_TeXcolor`` stands for the CSS property "color", i.e. it influences the text color of the contents. As for the three other options, @@ -1347,19 +1360,16 @@ forget the underscore separating the prefix from the property names. start of the contents; for admonitions, this happens after the heading which reproduces the admonition type. -The next keys, for admonitions only, were all three added at 7.4.0. The -default colors are the ones applying to the current HTML rendering of Sphinx -own docs at https://www.sphinx-doc.org. +The next keys, for admonitions, :dudir:`topic`, contents_, and +:dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three). - ``div._title-background-TeXcolor``: the background color for the title. .. important:: The colored title-row is produced as a result of the Sphinx default - definitions for the various ``\sphinxstyletitle`` commands, see - :ref:`latex-macros`. Custom redefinitions of these commands are - possible, but to re-use the colors and the icon, it is needed to check in - Sphinx LaTeX source code how the default definitions are done. + definitions for the various ``\sphinxstyletitle`` commands, which + employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. - ``div._title-foreground-TeXcolor``: the color to be used for the icon (it applies only to the icon, not to the title of the admonition). @@ -1436,24 +1446,19 @@ own docs at https://www.sphinx-doc.org. .. _ellipse: https://ctan.org/pkg/ellipse -The following legacy behavior is currently not customizable: +The following legacy behavior applies: -- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds - one) will go into the margin; the code lines remain at the same place - independently of the values of the padding and border-width, except for - being shifted vertically of course to not overwrite other text due to the - width of the border or external shadow. +- For :rst:dir:`code-block` or :rst:dir:`literalinclude`, padding and + border-width and shadow (if any) will go into the margin; the code + lines remain at the same place independently of the values of the padding + and border-width, except for being shifted vertically of course to not + overwrite other text due to the width of the border or external shadow. -- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the - page margin, but the border and the extra padding are kept within the text - area. Same for admonitions. +- For the other directives, shadows extend horizontally into the page margins, + but the border and the extra padding are kept within the text area. -- The contents_ and :dudir:`topic` directives are governed by the same options - with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives - the same ``sphinxShadowBox`` environment which has currently no additional - branching, contrarily to the ``sphinxadmonition`` environment which branches - according to the admonition directive name, e.g. either to ``sphinxnote`` - or ``sphinxwarning`` etc... +- :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX + environment and commands and are not separately customizable. LaTeX macros and environments @@ -1572,30 +1577,34 @@ Macros ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` - ``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}`` - ``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}`` - ``\sphinxstyleimportanttitle``; *similar* - ``\sphinxstyletiptitle``; *similar* - ``\sphinxstylewarningtitle``; *similar* - ``\sphinxstylecautiontitle``; *similar* - ``\sphinxstyleattentiontitle``; *similar* - ``\sphinxstyledangertitle``; *similar* - ``\sphinxstyleerrortitle``; *similar* - ``\sphinxstyleseealsotitle``; *similar* - ``\sphinxstyletodotitle``; *similar* + ``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}`` + ``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}`` + ``\sphinxstyleimportanttitle``; ``\sphinxdotitlerow{important}{#1}`` + ``\sphinxstyletiptitle``; ``\sphinxdotitlerow{tip}{#1}`` + ``\sphinxstylewarningtitle``; ``\sphinxdotitlerow{warning}{#1}`` + ``\sphinxstylecautiontitle``; ``\sphinxdotitlerow{caution}{#1}`` + ``\sphinxstyleattentiontitle``; ``\sphinxdotitlerow{attention}{#1}`` + ``\sphinxstyledangertitle``; ``\sphinxdotitlerow{danger}{#1}`` + ``\sphinxstyleerrortitle``; ``\sphinxdotitlerow{error}{#1}`` + ``\sphinxstyleseealsotitle``; ``\sphinxdotitlerow{seealso}{#1}`` + ``\sphinxstyletodotitle``; ``\sphinxdotitlerow{todo}{#1}`` + ``\sphinxstyletopictitle``; ``\sphinxdotitlerow{topic}{#1}`` + ``\sphinxstylecontentstitle``; ``\sphinxdotitlerow{contents}{#1}`` + ``\sphinxstylesidebartitle``; ``\sphinxdotitlerow{sidebar}{#1}`` .. note:: - To let this table fit on the page width in PDF output we have lied a bit - and the actual definition of ``\sphinxstylenotetitle`` is: + To let this table fit on the page width in PDF output we have lied a bit. + For instance, the actual definition of ``\sphinxstylenotetitle`` is: .. code-block:: latex \newcommand\sphinxstylenotetitle[1]% - {\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}} + {\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}} The same remark applies to all other similar commands associated with - admonitions. + admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not + use ``\sphinxremovefinalcolon`` as they don't need it. .. versionadded:: 1.5 These macros were formerly hard-coded as non customizable ``\texttt``, @@ -1616,14 +1625,20 @@ Macros directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` if this final colon is to be removed. - .. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command, - whose first argument is the admonition type, so that it can recover - the associated colours and icon for the title row, and the second - argument gets typeset after the icon. + .. versionadded:: 7.4.0 + Added the ``\sphinxdotitlerowwithicon`` LaTeX command. + + .. versionchanged:: 8.1.0 + ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is + associated or not with the rendered element used as first argument. + + .. versionadded:: 8.1.0 + Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``. - .. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a - legacy artefact from old ill-designed Sphinx LaTeX writer, - which postfixes (still today) the title with a colon automatically. + .. versionadded:: 8.1.0 + Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are + also styled using ``\sphinxdotitlerow`` (they have no default icons + associated with them). - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard @@ -1799,17 +1814,19 @@ Environments .. versionadded:: 6.1.0 .. versionchanged:: 6.2.0 - Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally. - Environment for the :rst:dir:`todo` directive: ``sphinxtodo``. - It takes one argument which will be the localized string ``Todo`` - followed with a colon. + It takes one argument, namely the localization of ``Todo`` + (with a colon at the end; the default rendering will remove that + colon and put the localized string in its own colored title-row). .. versionadded:: 7.4.0 -- The contents_ directive (with ``:local:`` option) and the - :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. + +- The :dudir:`topic`, contents_ and :dudir:`sidebar` directives + are associated with respectively ``sphinxtopic``, ``sphinxcontents``, + and ``sphinxsidebar`` environments. .. versionadded:: 1.4.2 Former code refactored into an environment allowing page breaks. @@ -1817,7 +1834,12 @@ Environments .. versionchanged:: 1.5 Options ``shadowsep``, ``shadowsize``, ``shadowrule``. -- The literal blocks (via ``::`` or :rst:dir:`code-block`), are + .. versionadded:: 8.1.0 + Separate environments (all three wrappers around ``sphinxShadowBox``) + and separate customizability. + +- The literal blocks (via ``::`` or :rst:dir:`code-block`), and literal + includes (:rst:dir:`literalinclude`) 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 diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 5c5f2f7a606..0d9a5ddc747 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -9,7 +9,7 @@ % by the Sphinx LaTeX writer. \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2024/07/01 v7.4.0 Sphinx LaTeX package (sphinx-doc)] +\ProvidesPackage{sphinx}[2024/07/28 v8.1.0 Sphinx LaTeX package (sphinx-doc)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -351,6 +351,11 @@ % is handled as an admonition with the same customizability. And the % todo directive. % +% 8.1.0: style separately topic, contents, and sidebar directives +% --------------------------------------------------------------- +% +% And use some title row also for them (but without icon, per default). +% \def\spxstring@none{none} \def\spxstring@clone{clone} % @@ -398,6 +403,15 @@ % macro prefix option prefix legacy option init value \spx@tempa{spx@pre@} {pre_} {verbatimborder} {0.4pt} \spx@tempa{spx@topic@} {div.topic_} {shadowrule} {0.5pt}% mod. at 7.4.0 +\spx@tempa{spx@contents@} {div.contents_} {shadowrule} {0.5pt}% 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% 8.1.0 +% let legacy shadowrule key set all topic/contents/sidebar border +% keys to the common value given by user to shadowrule +\def\KV@sphinx@shadowrule #1{% + \@nameuse{KV@sphinx@div.topic_border-width}{#1}% + \@nameuse{KV@sphinx@div.contents_border-width}{#1}% + \@nameuse{KV@sphinx@div.sidebar_border-width}{#1}% +}% \spx@tempa{spx@note@} {div.note_} {noteborder} {0.5pt} \spx@tempa{spx@hint@} {div.hint_} {hintborder} {0.5pt} \spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt} @@ -445,9 +459,13 @@ % In order for perfect exact same vertical alignment of contents from all such % directives, the value of horizontal border-width+padding is kept constant % (equal to 7.5pt since 7.4.0). +% 8.1.0 styles separately topic, contents, and sidebar. % #1 macro prefix #6 option prefix top right bottom left \spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} -\spx@tempa{spx@topic@} {div.topic_} {10pt}{7pt}{12pt}{7pt} +\spx@tempa{spx@topic@} {div.topic_} {6pt}{7pt}{6pt}{7pt}% mod. at 8.1.0 +% contents styling inherits at 8.1.0 the former 7.4.0 topic defaults +\spx@tempa{spx@contents@} {div.contents_} {10pt}{7pt}{12pt}{7pt}% 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{6.5pt}{6pt}{6.5pt}% 8.1.0 % 7.4.0 drops legacy settings which linked strangely padding with border width \spx@tempa{spx@note@} {div.note_} {6pt}{7pt}{6pt}{7pt} \spx@tempa{spx@hint@} {div.hint_} {6pt}{7pt}{6pt}{7pt} @@ -463,8 +481,13 @@ \spx@tempa{spx@box@} {box_} {3pt}{3pt}{3pt}{3pt} % define legacy verbatimsep key as alias of pre_padding key \expandafter\let\expandafter\KV@sphinx@verbatimsep\csname KV@sphinx@pre_padding\endcsname -% define legacy shadowsep key as alias of div.topic_padding key -\expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname +% let legacy shadowsep key set all topic/contents/sidebar padding +% keys to the common value given by user to shadosep +\def\KV@sphinx@shadowsep #1{% + \@nameuse{KV@sphinx@div.topic_padding}{#1}% + \@nameuse{KV@sphinx@div.contents_padding}{#1}% + \@nameuse{KV@sphinx@div.sidebar_padding}{#1}% +}% % Corner radii keys % @@ -492,9 +515,16 @@ % - the 3pt is used (which is normal value of \fboxsep). % - some admonitions use rounded corners as well. % - topic boxed have only their bottom right corner rounded. +% At 8.1.0 topic, contents and sidebar separately styled. % macro prefix option prefix tl tr br bl \spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} -\spx@tempa{spx@topic@} {div.topic_} \z@ \z@ {12pt} \z@ +% use four rounded corners (and no shadow) for topic at 8.1.0 +\spx@tempa{spx@topic@} {div.topic_} {8pt}{8pt}{8pt}{8pt} +% contents inherits at 8.1.0 the 7.4.0 former styling of topic +\spx@tempa{spx@contents@} {div.contents_} \z@ \z@ {12pt} \z@ +% make sidebard distinctive as we can't really safely implement +% it with text flowing around it, but rather as a full width block +\spx@tempa{spx@sidebar@} {div.sidebar_} {12pt}\z@ {12pt} \z@ \spx@tempa{spx@note@} {div.note_} {5pt}{5pt}{5pt}{5pt} \spx@tempa{spx@hint@} {div.hint_} {5pt}{5pt}{5pt}{5pt} \spx@tempa{spx@important@}{div.important_} \z@\z@\z@\z@ @@ -523,6 +553,8 @@ % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@contents@}% 8.1.0 +\spx@tempa{spx@sidebar@}% 8.1.0 \spx@tempa{spx@note@} \spx@tempa{spx@hint@} \spx@tempa{spx@important@} @@ -556,13 +588,10 @@ % used here. Since 6.2.0, expansion is delayed to time of use as for % the other dimensions handled above. This is synched with an added % encapsulation in \dimexpr...\relax by the "setup" from - % sphinxpackageboxes.sty. An induced regression had to be fixed in - % the sphinxShadowBox environment as it was using in an \ifdim the - % \spx@topic@shadow@yoffset macro, now holding by default 4pt+\z@ - % rather than an already digested 262144sp. The +\z@ is in case ##2 - % is empty. + % sphinxpackageboxes.sty. \else #1% - \def#6{##1}\def#7{##2+\z@}% + \def#6{##1}% + \if\relax\detokenize{##2}\relax\let#7#6\else\def#7{##2}\fi \if\relax\detokenize{##3}\relax#4\else#3\fi \fi }% @@ -570,8 +599,12 @@ } \spx@tempa{spx@pre@} {pre_} \spx@tempa{spx@topic@} {div.topic_} -% This corresponds to the legacy parameters of ShadowBox - \spx@topic@shadow@setter 4pt 4pt {} \@nnil +\spx@tempa{spx@contents@} {div.contents_} +\spx@tempa{spx@sidebar@} {div.sidebar_} +% This corresponds to the legacy parameters for topic/contents/sidebar, +% but they are now only kept for contents + \spx@contents@shadow@setter 4pt 4pt {} \@nnil +% topic and sidebar default to no shadow \spx@tempa{spx@note@} {div.note_} \spx@tempa{spx@hint@} {div.hint_} \spx@tempa{spx@important@}{div.important_} @@ -585,18 +618,28 @@ \spx@tempa{spx@error@} {div.error_} \spx@tempa{spx@box@} {box_} -% Support for legacy shadowsize (topic/contents) +% Support for legacy shadowsize (topic/contents/sidebar) % This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2 % MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef. Reason is to % keep in sync with div.topic_box-shadow handling of xoffset and yoffset. \define@key{sphinx}{shadowsize}{% \def\spx@topic@shadow@xoffset{#1}% - \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset + \let\spx@contents@shadow@xoffset\spx@topic@shadow@xoffset + \let\spx@sidebar@shadow@xoffset \spx@topic@shadow@xoffset + \let\spx@topic@shadow@yoffset \spx@topic@shadow@xoffset + \let\spx@contents@shadow@yoffset\spx@topic@shadow@xoffset + \let\spx@sidebar@shadow@yoffset \spx@topic@shadow@xoffset \ifdim\dimexpr\spx@topic@shadow@xoffset=\z@ \spx@topic@withshadowfalse + \spx@contents@withshadowfalse + \spx@sidebar@withshadowfalse \else \spx@topic@withshadowtrue \spx@topic@insetshadowfalse + \spx@contents@withshadowtrue + \spx@contents@insetshadowfalse + \spx@sidebar@withshadowtrue + \spx@sidebar@insetshadowfalse \fi }% @@ -639,6 +682,8 @@ % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@contents@} +\spx@tempa{spx@sidebar@} \spx@tempa{spx@note@} \spx@tempa{spx@hint@} \spx@tempa{spx@important@} @@ -691,7 +736,11 @@ \csname KV@sphinx@pre_background-TeXcolor\endcsname % (6.2.0 modified some internal namings for the colors of topic boxes) % macro prefix option prefix color name prefix -\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}% (no legacy interface) +% There was no legacy interface for topic/contents/sidebar +% 8.1.0 allows separate styling for topic/contents/sidebar +\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic} +\spx@tempa{spx@contents@} {div.contents_} {sphinxcontents} +\spx@tempa{spx@sidebar@} {div.sidebar_} {sphinxsidebar} \spx@tempa{spx@note@} {div.note_} {sphinxnote} \spx@tempa{spx@hint@} {div.hint_} {sphinxhint} \spx@tempa{spx@important@}{div.important_} {sphinximportant} @@ -744,10 +793,19 @@ % At 7.4.0, let topic/contents boxes acquire background and border colours % and give the shadow some colour other than black - \setkeys{sphinx}{div.topic_border-TeXcolor=sphinx-admonition-bordercolor, - div.topic_background-TeXcolor=sphinx-admonition-bgcolor, - div.topic_box-shadow-TeXcolor={RGB}{108,108,108}, - } + % 8.1.0 styles separately topic/contents/sidebar + % topic has no shadow but we keep 7.4.0 color in case it gets needed + \setkeys{sphinx}{% + div.topic_border-TeXcolor=sphinx-admonition-bordercolor, + div.topic_background-TeXcolor=sphinx-admonition-bgcolor, + div.topic_box-shadow-TeXcolor={RGB}{108,108,108}, + div.contents_border-TeXcolor=sphinx-admonition-bordercolor, + div.contents_background-TeXcolor=sphinx-admonition-bgcolor, + div.contents_box-shadow-TeXcolor={RGB}{108,108,108}, + div.sidebar_border-TeXcolor=sphinx-admonition-bordercolor, + div.sidebar_background-TeXcolor=sphinx-admonition-bgcolor, + div.sidebar_box-shadow-TeXcolor=sphinx-admonition-bordercolor!80,% #9eacaf + } % 7.4.0 lets all types of admonitions style especially their titlss. @@ -800,8 +858,14 @@ div.error_title-background-TeXcolor=sphinx-error-title-bgcolor, div.error_title-foreground-TeXcolor=sphinx-error-title-fgcolor, % -% TODO: implement todo (sic) -% +% 8.1.0 add title rows, but will not use icons per default, so +% the fgcolor setting will be used only if user uses title-icon key + div.topic_title-background-TeXcolor=sphinx-admonition-title-bgcolor, + div.topic_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor, + div.contents_title-background-TeXcolor=sphinx-admonition-title-bgcolor, + div.contents_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor, + div.sidebar_title-background-TeXcolor=sphinx-note-title-bgcolor, + div.sidebar_title-foreground-TeXcolor=sphinx-note-title-fgcolor, } % 7.4.0 Support for icons in admonition titles @@ -882,6 +946,9 @@ div.attention_title-icon = \spx@faIcon{exclamation-triangle}, div.danger_title-icon = \spx@faIcon{radiation}, div.error_title-icon = \spx@faIcon{times-circle}, +% MEMO: the new at 8.1.0 defaults for contents/topic/sidebar directives +% use no icons, they use \sphinxdotitlerow which detects automatically +% whether title-icon key has been set or not. } \newif\ifspx@opt@box@addstrut diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 0f49acacf5e..2d50b2eb313 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -1,15 +1,12 @@ %% NOTICES AND ADMONITIONS % % change this info string if making any custom modification -\ProvidesPackage{sphinxlatexadmonitions}[2024/07/01 v7.4.0 admonitions] +\ProvidesPackage{sphinxlatexadmonitions}[2024/07/28 v8.1.0 admonitions] % Provides support for this output mark-up from Sphinx latex writer: % % - sphinxseealso environment added at 6.1.0. % -% At 7.4.0 it too now uses sphinxheavybox, and has the same associated -% sphinxsetup CSS keys as admonitions do. -% % - sphinxtodo environment added at 7.4.0. % % - sphinxadmonition (environment) @@ -19,16 +16,21 @@ % sphinxheavybox since 6.2.0), % - warning, caution, attention, danger, error to use sphinxheavybox. % -% At 7.4.0 all admonitions use sphinxheavybox. +% Since 7.4.0 all admonitions use sphinxheavybox. % % - All environments sphinxnote, sphinxwarning, etc... can be redefined as % will by user. Thay have a single parameter #1 which is the title. % -% - The default sphinxnote, sphinxwarning, etc... use associated -% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc -% which can be redefined. Their default is to use \sphinxdotitlerowwithicon -% to typeset the title in a coloured header row at top of the -% admonition. (new with 7.4.0) +% - Also redefinable by user are the one-argument commands +% * \sphinxstylenotetitle, +% * \sphinxstylewarningtitle, +% * etc.... one for each admonition type (also seealso and todo). +% +% - At 7.4.0, all commands of previous item use \sphinxdotitlerow. +% (the 7.4.0 name, still usable, was \sphinxdotitlerowwithicon; the 8.1.0 +% version is also used for topic, contents and sidebar directives, see +% sphinxlatexshadowbox.sty, and handles both "with icon" and "without +% icon" situations). % % The sphinxlightbox environment is kept for backward compatiblity, for user % custom code which used it via custom definitions done in preamble or via @@ -42,20 +44,21 @@ % (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox, % so \sphinxstrong{#1} which was its former default is used above). -% -% Requires: -\RequirePackage{sphinxpackageboxes} -% 7.4.0 removes unneeded \spx@boxes@border -\RequirePackage{framed}% used by sphinxheavybox -% % Dependencies (they do not need to be defined at time of loading): % % - of course the various colour and dimension options handled via sphinx.sty -% % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty +% - \savenotes/\spewnotes from sphinxpackagefootnote.sty +% - \ifspx@inframed defined in sphinx.sty +% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty +% +\RequirePackage{framed} +% Those are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: +\RequirePackage{sphinxlatexgraphics} +\RequirePackage{sphinxpackagefootnote} +\RequirePackage{sphinxpackageboxes} % -% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox) - % Provides: (also in sphinxlatexliterals.sty) % Only needed here by legacy (deprecated) sphinxlightbox environment. \providecommand*\sphinxvspacefixafterfrenchlists{% @@ -300,10 +303,15 @@ % workaround some LaTeX "feature" of \end command (i.e. can't use "sphinx#1" here) {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp} +% TODO: allow these next three settings to be customized individually. +% This can however already be done at user level by \renewcommand +% inside renew'ed environments sphinxnote, sphinxhint etc... \newcommand\sphinxtitlerowtoppadding{5pt} \newcommand\sphinxtitlerowbottompadding{3pt} \newcommand\sphinxtitlerowaftericonspacecmd{\hskip0.5em\relax} -\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon) +% 7.4.0 used this longer name: +\newcommand\sphinxdotitlerowwithicon{\sphinxdotitlerow} +\newcommand\sphinxdotitlerow[2]{% #1=type, #2=heading (without final colon) \begingroup \kern-\spx@boxes@padding@top \parskip\z@skip % the \parskip business is a workaround to a vertical @@ -325,16 +333,24 @@ \spx@boxes@withshadowfalse \sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}% \spx@boxes@fcolorbox{% - \makebox[\linewidth][l]{% - \textcolor{sphinx#1TtlFgColor}{% + \parbox[t]{\linewidth}{% 7.4.0 used \makebox, but wrapping of long titles + % is needed for generic admonition or topic box. + \sphinxAtStartPar + % 8.1.0 auto-drops extra space if no icon + \sbox\z@{\@nameuse{sphinx#1TtlIcon}}% + \ifdim\wd\z@>\z@ + \textcolor{sphinx#1TtlFgColor}{% \@nameuse{sphinx#1TtlIcon}% % This macro is located here and not after the closing brace % for reasons of fall-back \spx@faIcon definition in sphinx.sty % in case fontawesome5 package not found. \sphinxtitlerowaftericonspacecmd - }% + }% + \fi \sphinxstrong{#2}% - \strut}% + \strut + \par + }% }% \kern-\spx@boxes@padding@right \par @@ -347,17 +363,17 @@ % \sphinxremovefinalcolon{#1} will typeset #1 without the colon. % Legacy definitions (done in sphinxlatexstyletext.sty) were all using % a boring plain \sphinxstrong{#1}, now we use a coloured title row. -\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerowwithicon{hint}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerowwithicon{important}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerowwithicon{tip}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerowwithicon{warning}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerowwithicon{caution}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerowwithicon{attention}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}} -\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerowwithicon{todo}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerow{hint}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerow{important}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerow{tip}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerow{warning}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerow{caution}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerow{attention}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerow{danger}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerow{error}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerow{seealso}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerow{todo}{\sphinxremovefinalcolon{#1}}} % % A utility to remove a final colon. Removing last token is not easy in % LaTeX, and there are additional complications: diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 7fffac22ca5..53a333845aa 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -1,21 +1,37 @@ %% TOPIC AND CONTENTS BOXES % % change this info string if making any custom modification -\ProvidesPackage{sphinxlatexshadowbox}[2023/03/19 sphinxShadowBox] +\ProvidesPackage{sphinxlatexshadowbox}[2024/07/28 v8.1.0 sphinxShadowBox] % Provides support for this output mark-up from Sphinx latex writer: % -% - sphinxShadowBox (environment) +% - Environments: sphinxtopic, sphinxcontents, and sphinxsidebar. +% +% These wrappers replace at 8.1.0 former direct use of sphinxShadowBox +% environment which did not allow separate styling. +% +% - Commands: \sphinxstyletopictitle, \sphinxstylecontentstitle, and +% \sphinxstylesidebartitle. +% +% At 8.1.0 they default to use \sphinxdotitlerow whose definiion is done in +% sphinxlatexadmonitions.sty. There is also \sphinxstylesidebarsubtitle +% which does not use \sphinxdotitlerow. % % Dependencies (they do not need to be defined at time of loading): % % - of course the various colour and dimension options handled via sphinx.sty % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty -% - \savenotes/\spewnotes from sphinxpackagefootnote +% - \savenotes/\spewnotes from sphinxpackagefootnote.sty % - \ifspx@inframed defined in sphinx.sty +% - \sphinxdotitlerow from sphinxlatexadmonitions.sty +% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty % -% Requires: \RequirePackage{framed} +% Those are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: +\RequirePackage{sphinxlatexgraphics} +\RequirePackage{sphinxpackagefootnote} +\RequirePackage{sphinxlatexadmonitions} \RequirePackage{sphinxpackageboxes} % At 5.1.0 the code formerly here in a definition of \spx@ShadowFBox has been @@ -45,9 +61,28 @@ % in contrast with the framing used for literal blocks, also based, but in a % more sophisticated way on usage of \MakeFramed/\endMakeFramed, and % adjusting to current text indentation. -\newenvironment{sphinxShadowBox} +% +% At 8.1.0, sphinxShadowBox takes an optional argument #1 and uses it as +% \spx@boxes@fcolorbox@setup{#1} rather than \spx@boxes@fcolorbox@setup{topic}. +% Some hesitation whether to move this line to newly added sphinxtopic, +% sphinxcontents and sphinxsidebar environmments. But anyhow the environment +% also requires later knowing a few more things: sphinxTextColor and +% spx@@texextras. +% +% The #1 defaulting to topic must be such that all parameters expected by +% \spx@boxes@fcolorbox@setup actually do exist, see CSS options in sphinx.sty +% which is what defines them for contents, topic, and sidebar. +% +% Fortunately the #1 is not needed in \end{sphinxShadowBox} so we don't have +% to work around a LaTeX conception bug that such #1 can not be used as is in +% the definition of the \end part of an environment. +% +% MEMO: the "shadow" is not really drawn directly by this environment but +% indirectly via the configuration which is passed over to \spx@boxes@fcolorbox, +% which is the macro creating frame and (perhaps but not necessarily) a shadow. +\newenvironment{sphinxShadowBox}[1][topic]% {% - \spx@boxes@fcolorbox@setup{topic}% + \spx@boxes@fcolorbox@setup{#1}% % we will use the dimen registers from sphinxpackageboxes.sty which now hold % the values from options related to topic/contents % MEMO: \spx@boxes@fcolorbox creates an \hbox but does not quit vertical @@ -56,7 +91,7 @@ \def\FrameCommand {\spx@boxes@fcolorbox}% % 6.2.0 adds support for div.topic_box-decoration-break=slice. % (it is yet undecided if slice style should inhibit a bottom shadow) - \ifspx@topic@border@open + \@nameuse{ifspx@#1@border@open}% \def\FirstFrameCommand {\spx@boxes@fcolorbox@setup@openbottom\FrameCommand}% \def\MidFrameCommand @@ -97,10 +132,10 @@ \@setminipage }% \color@begingroup % workaround upstream framed.sty bug - \ifspx@topic@withtextcolor - \color{sphinxtopicTextColor}% + \@nameuse{ifspx@#1@withtextcolor}% + \color{sphinx#1TextColor}% \fi - \spx@topic@TeXextras + \@nameuse{spx@#1@TeXextras}% }% {% insert the "endminipage" code \par\unskip @@ -113,4 +148,31 @@ \spewnotes } +% 8.1.0 +\newenvironment{sphinxtopic} + {\begin{sphinxShadowBox}[topic]}{\end{sphinxShadowBox}} +\newenvironment{sphinxcontents} + {\begin{sphinxShadowBox}[contents]}{\end{sphinxShadowBox}} +% Arguably sphinxsidebar should rather use a wrapfig or similar environment +% but this is so dysfunctional in LaTeX (except for self-written documents) +% so we prefer to not venture into such a potential quagmire and keep the +% legacy rendering using a full width display. +\newenvironment{sphinxsidebar} + {\begin{sphinxShadowBox}[sidebar]}{\end{sphinxShadowBox}} + +% TODO: decide if this should be in sphinxlatexstyletext.sty rather +% +% 8.1.0 styles topic/contents/sidebar with a title row, too. +% Prior to 8.1.0, definitions use \protected\def but there does not seem +% to be any reason so back to \newcommand. +\newcommand*\sphinxstyletopictitle[1]{\sphinxdotitlerow{topic}{#1}} +\newcommand*\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}} +\newcommand*\sphinxstylesidebartitle[1]{\sphinxdotitlerow{sidebar}{#1}} +% No default color background for subtitle. The contents next are injected by +% LaTeX writer after a blank line in source hence will start a new paragrpah. +% The \sphinxAtStartPar here is only for coherence with other text paragraphs, +% but does not have serious necessity (its general role is to allow hyphenation +% for first word in narrow table cells). +\newcommand*\sphinxstylesidebarsubtitle[1]{\sphinxAtStartPar\textbf{#1}} + \endinput diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index 962971d22d4..d083cd96a83 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -1,9 +1,10 @@ %% TEXT STYLING % % change this info string if making any custom modification -\ProvidesPackage{sphinxlatexstyletext}[2024/07/01 v7.4.0 text styling] +\ProvidesPackage{sphinxlatexstyletext}[2024/07/28 v8.1.0 text styling] % 7.4.0 has moved all that is related to admonitions to sphinxlatexadmonitions.sty +% 8.1.0 has moved topic/contents/sidebar to sphinxlatexshadowbox.sty % Most everything left here consists of macros which are part of the latex markup % produced by the Sphinx LaTeX writer. @@ -39,10 +40,7 @@ {{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \def\sphinxstyleindexlettergroupDefault #1% {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}} -\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} -\let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} -\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip} % \text.. commands do not allow multiple paragraphs % attention, this one is not self-delimiting \protected\def\sphinxstyletheadfamily {\sffamily} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index daee856f918..0f2ffc29f0f 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -585,13 +585,22 @@ def depart_problematic(self, node: Element) -> None: self.body.append('}') def visit_topic(self, node: Element) -> None: - self.in_minipage = 1 - self.body.append(CR + r'\begin{sphinxShadowBox}' + CR) + self.in_minipage += 1 + if 'contents' in node.get('classes', []): + self.body.append(CR + r'\begin{sphinxcontents}' + CR) + self.context.append(r'\end{sphinxcontents}' + CR) + else: + self.body.append(CR + r'\begin{sphinxtopic}' + CR) + self.context.append(r'\end{sphinxtopic}' + CR) def depart_topic(self, node: Element) -> None: - self.in_minipage = 0 - self.body.append(r'\end{sphinxShadowBox}' + CR) - visit_sidebar = visit_topic + self.in_minipage -= 1 + self.body.append(self.context.pop()) + + def visit_sidebar(self, node: Element) -> None: + self.in_minipage += 1 + self.body.append(CR + r'\begin{sphinxsidebar}' + CR) + self.context.append(r'\end{sphinxsidebar}' + CR) depart_sidebar = depart_topic def visit_glossary(self, node: Element) -> None: @@ -654,7 +663,10 @@ def visit_title(self, node: Element) -> None: self.body.append(fr'\{self.sectionnames[-1]}{short}{{') self.context.append('}' + CR + self.hypertarget_to(node.parent)) elif isinstance(parent, nodes.topic): - self.body.append(r'\sphinxstyletopictitle{') + if 'contents' in parent.get('classes', []): + self.body.append(r'\sphinxstylecontentstitle{') + else: + self.body.append(r'\sphinxstyletopictitle{') self.context.append('}' + CR) elif isinstance(parent, nodes.sidebar): self.body.append(r'\sphinxstylesidebartitle{') diff --git a/tests/roots/test-latex-contents-topic-sidebar/conf.py b/tests/roots/test-latex-contents-topic-sidebar/conf.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/roots/test-latex-contents-topic-sidebar/index.rst b/tests/roots/test-latex-contents-topic-sidebar/index.rst new file mode 100644 index 00000000000..d47e867f64d --- /dev/null +++ b/tests/roots/test-latex-contents-topic-sidebar/index.rst @@ -0,0 +1,19 @@ +test-contents-et-al +=================== + +.. contents:: + +test-topic +---------- + +.. topic:: Title of topic + + text of topic + +test-sidebar +------------ + +.. sidebar:: Title of sidebar + :subtitle: sub-title + + text of sidebar diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py index 1cc5c2f8fc7..21ec2922e97 100644 --- a/tests/roots/test-root/conf.py +++ b/tests/roots/test-root/conf.py @@ -70,10 +70,15 @@ % shadowrule=1pt, shadowsep=10pt, - shadowsize=10pt, - div.topic_border-width=2pt,% alias to shadowrule - div.topic_padding=6pt,% alias to shadowsep - div.topic_box-shadow=5pt,% overrides/alias shadowsize + shadowsize=-10pt, + div.topic_border-width=2pt, + div.topic_padding=6pt, + div.topic_box-shadow=5pt, + div.contents_border-width=3pt, + div.contents_padding=10pt, + div.contents_box-shadow=none, + div.sidebar_border-width=0pt, + div.sidebar_border-radius=0pt, % noteBorderColor={RGB}{204,204,204}, hintBorderColor={RGB}{204,204,204}, diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 1d474f67691..2aa4e0ea565 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -2275,3 +2275,30 @@ def test_latex_rubric(app): content = (app.outdir / 'test.tex').read_text(encoding='utf8') assert r'\subsubsection*{This is a rubric}' in content assert r'\subsection*{A rubric with a heading level 2}' in content + + +@pytest.mark.sphinx('latex', testroot='latex-contents-topic-sidebar') +def test_latex_contents_topic_sidebar(app): + app.build() + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') + + assert '\\begin{sphinxcontents}\n\\sphinxstylecontentstitle{Contents}\n' in result + + assert ( + '\\begin{sphinxtopic}\n' + '\\sphinxstyletopictitle{Title of topic}\n' + '\n' + '\\sphinxAtStartPar\n' + 'text of topic\n' + '\\end{sphinxtopic}\n' + ) in result + + assert ( + '\\begin{sphinxsidebar}\n' + '\\sphinxstylesidebartitle{Title of sidebar}\n' + '\\sphinxstylesidebarsubtitle{sub\\sphinxhyphen{}title}\n' + '\n' + '\\sphinxAtStartPar\n' + 'text of sidebar\n' + '\\end{sphinxsidebar}\n' + ) in result From e54982f27cd4ea36cd932e65c06811bed09f2eae Mon Sep 17 00:00:00 2001 From: Frank Dana Date: Thu, 22 Aug 2024 05:09:13 -0400 Subject: [PATCH 08/12] Fix typo in ``sphinx-autogen`` documentation (#12809) --- doc/man/sphinx-autogen.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst index 43cc369b78b..fed230d2cc1 100644 --- a/doc/man/sphinx-autogen.rst +++ b/doc/man/sphinx-autogen.rst @@ -14,7 +14,7 @@ that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included in :rst:dir:`autosummary` listing(s). *sourcefile* is the path to one or more reStructuredText documents containing -:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile* +:rst:dir:`autosummary` entries with the ``:toctree:`` option set. *sourcefile* can be an :py:mod:`fnmatch`-style pattern. Options From 67e460bc902ce4429202053c03e09e988ab602d6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 22 Aug 2024 10:09:49 +0100 Subject: [PATCH 09/12] Bump types-pillow to 10.2.0.20240822 (#12810) --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index dcca55027f8..96aa09271e8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -87,7 +87,7 @@ lint = [ "types-colorama==0.4.15.20240311", "types-defusedxml==0.7.0.20240218", "types-docutils==0.21.0.20240724", - "types-Pillow==10.2.0.20240520", + "types-Pillow==10.2.0.20240822", "types-Pygments==2.18.0.20240506", "types-requests>=2.30.0", # align with requests "tomli>=2", # for mypy (Python<=3.10) From 1852d0f087bf09227886c5bd7b144383ac5c6eea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?= <10796600+picnixz@users.noreply.github.com> Date: Thu, 22 Aug 2024 11:11:12 +0200 Subject: [PATCH 10/12] intersphinx: Fix double forward slashes in inventory urls (#12807) --- CHANGES.rst | 4 ++ sphinx/ext/intersphinx/_load.py | 5 +- tests/test_extensions/test_ext_intersphinx.py | 71 +++++++++++++++++++ 3 files changed, 79 insertions(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 3f0ce6e7ba0..5785d62ef95 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -83,6 +83,10 @@ Bugs fixed e.g., ``index.html#foo`` becomes ``#foo``. (note: continuation of a partial fix added in Sphinx 7.3.0) Patch by James Addison (with reference to prior work by Eric Norige) +* #12782: intersphinx: fix double forward slashes when generating the inventory + file URL (user-defined base URL of an intersphinx project are left untouched + even if they end with double forward slashes). + Patch by Bénédikt Tran. Testing ------- diff --git a/sphinx/ext/intersphinx/_load.py b/sphinx/ext/intersphinx/_load.py index 1973de379be..358ae1f7ccb 100644 --- a/sphinx/ext/intersphinx/_load.py +++ b/sphinx/ext/intersphinx/_load.py @@ -211,7 +211,10 @@ def _fetch_inventory_group( for location in project.locations: # location is either None or a non-empty string - inv = f'{project.target_uri}/{INVENTORY_FILENAME}' if location is None else location + if location is None: + inv = posixpath.join(project.target_uri, INVENTORY_FILENAME) + else: + inv = location # decide whether the inventory must be read: always read local # files; remote ones only if the cache time is expired diff --git a/tests/test_extensions/test_ext_intersphinx.py b/tests/test_extensions/test_ext_intersphinx.py index c41ac982ce5..99dde92a57f 100644 --- a/tests/test_extensions/test_ext_intersphinx.py +++ b/tests/test_extensions/test_ext_intersphinx.py @@ -12,6 +12,7 @@ from sphinx import addnodes from sphinx.builders.html import INVENTORY_FILENAME +from sphinx.config import Config from sphinx.errors import ConfigError from sphinx.ext.intersphinx import ( inspect_main, @@ -768,3 +769,73 @@ def test_intersphinx_cache_limit(app): config=app.config, srcdir=app.srcdir, ) + + +def test_intersphinx_fetch_inventory_group_url(): + class InventoryHandler(http.server.BaseHTTPRequestHandler): + def do_GET(self): + self.send_response(200, 'OK') + self.end_headers() + self.wfile.write(INVENTORY_V2) + + def log_message(*args, **kwargs): + # Silenced. + pass + + with http_server(InventoryHandler) as server: + url1 = f'http://localhost:{server.server_port}' + url2 = f'http://localhost:{server.server_port}/' + + config = Config() + config.intersphinx_cache_limit = -1 + config.intersphinx_mapping = { + '1': (url1, None), + '2': (url2, None), + } + + now = int(time.time()) + # we can use 'srcdir=None' since we are raising in _fetch_inventory + kwds = {'cache': {}, 'now': now, 'config': config, 'srcdir': None} + # We need an exception with its 'args' attribute set (see error + # handling in sphinx.ext.intersphinx._load._fetch_inventory_group). + side_effect = ValueError('') + + project1 = _IntersphinxProject( + name='1', target_uri=url1, locations=(url1, None) + ) + with mock.patch( + 'sphinx.ext.intersphinx._load._fetch_inventory', side_effect=side_effect + ) as mockfn: + assert not _fetch_inventory_group(project=project1, **kwds) + mockfn.assert_any_call( + target_uri=url1, + inv_location=url1, + config=config, + srcdir=None, + ) + mockfn.assert_any_call( + target_uri=url1, + inv_location=url1 + '/' + INVENTORY_FILENAME, + config=config, + srcdir=None, + ) + + project2 = _IntersphinxProject( + name='2', target_uri=url2, locations=(url2, None) + ) + with mock.patch( + 'sphinx.ext.intersphinx._load._fetch_inventory', side_effect=side_effect + ) as mockfn: + assert not _fetch_inventory_group(project=project2, **kwds) + mockfn.assert_any_call( + target_uri=url2, + inv_location=url2, + config=config, + srcdir=None, + ) + mockfn.assert_any_call( + target_uri=url2, + inv_location=url2 + INVENTORY_FILENAME, + config=config, + srcdir=None, + ) From 9943274033130d218e1d8f253cc6040cbffeec92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Fri, 23 Aug 2024 18:04:38 +0200 Subject: [PATCH 11/12] LaTeX: clarify some docs, add syntax highlighting (refactoring) (#12818) --- doc/latex.rst | 491 +++++++++++++++++++----------------- doc/usage/configuration.rst | 51 ++-- 2 files changed, 283 insertions(+), 259 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 5c9c503565b..c53e25fcf40 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -4,6 +4,9 @@ LaTeX customization .. module:: latex :synopsis: LaTeX specifics. +.. role:: code-tex(code) + :language: LaTeX + .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents .. raw:: latex @@ -120,7 +123,7 @@ Keys that you may want to override include: ``'passoptionstopackages'`` A string which will be positioned early in the preamble, designed to - contain ``\\PassOptionsToPackage{options}{foo}`` commands. + contain :code-tex:`\\PassOptionsToPackage{options}{foo}` commands. .. hint:: @@ -133,7 +136,7 @@ Keys that you may want to override include: .. versionadded:: 1.4 ``'babel'`` - "babel" package inclusion, default ``'\\usepackage{babel}'`` (the + "babel" package inclusion, default :code-tex:`r'\\usepackage{babel}'` (the suitable document language string is passed as class option, and ``english`` is used if no language.) For Japanese documents, the default is the empty string. @@ -152,7 +155,7 @@ Keys that you may want to override include: build repertory before next PDF build, else left-over auxiliary files are likely to break the build. - Default: ``'\\usepackage{babel}'`` (for Japanese documents) + Default: :code-tex:`r'\\usepackage{babel}'` (for Japanese documents) .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default @@ -168,6 +171,8 @@ Keys that you may want to override include: .. versionchanged:: 7.4.0 For French with ``'lualatex'`` the default is to use ``babel``. +.. _fontpkg: + ``'fontpkg'`` Font package inclusion. The default is:: @@ -176,8 +181,11 @@ Keys that you may want to override include: \renewcommand\ttdefault{txtt} """ - For ``'xelatex'`` and ``'lualatex'`` however the default is to use - the GNU FreeFont. + For ``'xelatex'`` and ``'lualatex'`` on the other hand the + :code-tex:`\\setmainfont`, :code-tex:`\\setsansfont` and + :code-tex:`\\setmonofont` commands of LaTeX package ``fontspec`` (included + via :ref:`fontenc`) are used to set up the OpenType fonts GNU FreeSerif, + FreeSans, and FreeMono as document fonts. .. versionchanged:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic @@ -188,27 +196,25 @@ Keys that you may want to override include: Greek or Cyrillic in a document using ``'pdflatex'`` engine. .. versionchanged:: 4.0.0 - - - The font substitution commands added at ``2.0`` have been moved - to the ``'fontsubstitution'`` key, as their presence here made - it complicated for user to customize the value of ``'fontpkg'``. - - The default font setting has changed: it still uses Times and - Helvetica clones for serif and sans serif, but via better, more - complete TeX fonts and associated LaTeX packages. The - monospace font has been changed to better match the Times clone. + The default font setting was changed. As shown above it still uses + Times and Helvetica clones for serif and sans serif, but via better, + more complete TeX fonts and associated LaTeX packages. The monospace + font has been changed to better match the Times clone. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), - default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation + default :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English documentation (this option is slightly customized by Sphinx), - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because + :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to ``''`` to disable fncychap. - Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents, - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and - ``''`` for Japanese documents. + Default: :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English + documents, :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for + internationalized documents, and ``''`` for Japanese documents. + +.. _preamble: ``'preamble'`` Additional preamble content. One may move all needed macros into some file @@ -314,7 +320,7 @@ Keys that don't need to be overridden unless in special cases are: ``'inputenc'`` "inputenc" package inclusion. - Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else + Default: :code-tex:`r'\\usepackage[utf8]{inputenc}'` when using pdflatex, else ``''``. .. note:: @@ -340,63 +346,72 @@ Keys that don't need to be overridden unless in special cases are: ``utf8x`` is in use. .. versionchanged:: 1.4.3 - Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all + Previously :code-tex:`r'\\usepackage[utf8]{inputenc}'` was used for all compilers. ``'cmappkg'`` "cmap" package inclusion. - Default: ``'\\usepackage{cmap}'`` + Default: :code-tex:`r'\\usepackage{cmap}'` .. versionadded:: 1.2 +.. _fontenc: + ``'fontenc'`` - Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to: + Its default, for ``'pdflatex'`` as :confval:`latex_engine`, is + :code-tex:`r'\\usepackage[T1]{fontenc}'`. Replace it (if using + ``'pdflatex'``) with: - - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional + - :code-tex:`r'\\usepackage[X2,T1]{fontenc}'` if you need occasional Cyrillic letters (физика частиц), - - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional - Greek letters (Σωματιδιακή φυσική). + - :code-tex:`r'\\usepackage[LGR,T1]{fontenc}'` if you need occasional + Greek letters (Σωματιδιακή φυσική), - Use ``[LGR,X2,T1]`` rather if both are needed. + - :code-tex:`r'\\usepackage[LGR,X2,T1]{fontenc}'` if you need both. - .. attention:: + The TeX installation may need some extra packages. For example, on Ubuntu + xenial: - - Do not use this key for a :confval:`latex_engine` other than - ``'pdflatex'``. + - ``texlive-lang-greek`` and ``cm-super`` are needed for Greek (``LGR``), - - If Greek is main language, do not use this key. Since Sphinx 2.2.1, - ``xelatex`` will be used automatically as :confval:`latex_engine`. + - ``texlive-lang-cyrillic`` and ``cm-super`` are needed for Cyrillic + (``X2``). - - The TeX installation may need some extra packages. For example, - on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` - are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and - ``cm-super`` are needed for support of Cyrillic. + With ``'xelatex'`` and ``'lualatex'``, support for Greek and Cyrillic is + out-of-the-box: this :ref:`fontenc` key defaults to including the LaTeX + package ``fontspec`` (with some extras described below) and selects the GNU + FreeSerif font as body font. See :ref:`fontpkg`. .. versionchanged:: 1.5 - Defaults to ``'\\usepackage{fontspec}'`` when - :confval:`latex_engine` is ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'xelatex'``. .. versionchanged:: 1.6 - ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'lualatex'``. .. versionchanged:: 2.0 - ``'lualatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX - ligatures transforming ``<<`` and ``>>`` as escaping working with - ``pdflatex/xelatex`` failed with ``lualatex``. + ``'lualatex'`` executes additionally + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` to disable TeX + ligatures for ``<<`` and ``>>``. .. versionchanged:: 2.0 - Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of - occasional Greek or Cyrillic letters (``'pdflatex'``). + Extra LaTeX configuration is automatically executed if ``LGR``, ``T2A``, + or ``X2`` are detected in this key, in order to support occasional Greek + or Cyrillic with ``'pdflatex'``. + + .. versionchanged:: 2.2.1 + Documents having Greek as main language default to ``'xelatex'`` and + should not set the :ref:`fontenc` key, which will load ``fontspec``. .. versionchanged:: 2.3.0 ``'xelatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid - contractions of ``--`` into en-dash or transforms of straight quotes - into curly ones in PDF (in non-literal text paragraphs) despite - :confval:`smartquotes` being set to ``False``. + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` in order to + avoid contractions of ``--`` into en-dash and also transforms of + straight quotes into curly quotes (which otherwise would happen even + with :confval:`smartquotes` set to ``False``). ``'fontsubstitution'`` Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or @@ -413,7 +428,7 @@ Keys that don't need to be overridden unless in special cases are: It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as :confval:`latex_engine` and defaults to either the empty string or - to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on + to :code-tex:`r'\\usepackage{textalpha}'` for ``'pdflatex'`` depending on whether the ``'fontenc'`` key was used with ``LGR`` or not. Only expert LaTeX users may want to customize this key. @@ -421,20 +436,16 @@ Keys that don't need to be overridden unless in special cases are: ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context. For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`. - Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not + Default: :code-tex:`r'\\usepackage{textalpha}'` or ``''`` if ``fontenc`` does not include the ``LGR`` option. .. versionadded:: 2.0 ``'geometry'`` - "geometry" package inclusion, the default definition is: - - .. code-block:: latex - - '\\usepackage{geometry}' - - with an additional ``[dvipdfm]`` for Japanese documents. - The Sphinx LaTeX style file executes: + "geometry" package inclusion, defaults to + :code-tex:`r'\\usepackage{geometry}'` or + :code-tex:`r'\\usepackage[dvipdfm]{geometry}'` for Japanese documents. + The Sphinx LaTeX style file executes additionally: .. code-block:: latex @@ -443,9 +454,6 @@ Keys that don't need to be overridden unless in special cases are: which can be customized via corresponding :ref:`'sphinxsetup' options `. - Default: ``'\\usepackage{geometry}'`` (or - ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents) - .. versionadded:: 1.5 .. versionchanged:: 1.5.2 @@ -457,7 +465,8 @@ Keys that don't need to be overridden unless in special cases are: .. versionchanged:: 1.5.3 The location in the LaTeX file has been moved to after - ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after + :code-tex:`\\usepackage{sphinx}` and :code-tex:`\\sphinxsetup{..}`, + hence also after insertion of ``'fontpkg'`` key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the *zenkaku* width, and @@ -466,8 +475,8 @@ Keys that don't need to be overridden unless in special cases are: ``'hyperref'`` "hyperref" package inclusion; also loads package "hypcap" and issues - ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is - loaded and before executing the contents of ``'preamble'`` key. + :code-tex:`\\urlstyle{same}`. This is done after :file:`sphinx.sty` file + is loaded and before executing the contents of ``'preamble'`` key. .. attention:: @@ -483,18 +492,18 @@ Keys that don't need to be overridden unless in special cases are: .. hint:: If the key value is set to - ``r'\newcommand\sphinxbackoftitlepage{}\sphinxmaketitle'``, then ```` will be + :code-tex:`r'\\newcommand\sphinxbackoftitlepage{}\\sphinxmaketitle'`, then ```` will be typeset on back of title page (``'manual'`` docclass only). - Default: ``'\\sphinxmaketitle'`` + Default: :code-tex:`r'\\sphinxmaketitle'` .. versionchanged:: 1.8.3 - Original ``\maketitle`` from document class is not overwritten, + Original :code-tex:`\\maketitle` from document class is not overwritten, hence is reusable as part of some custom setting for this key. .. versionadded:: 1.8.3 - ``\sphinxbackoftitlepage`` optional macro. It can also be defined + :code-tex:`\\sphinxbackoftitlepage` optional macro. It can also be defined inside ``'preamble'`` key rather than this one. ``'releasename'`` @@ -505,72 +514,74 @@ Keys that don't need to be overridden unless in special cases are: Default: ``'Release'`` ``'tableofcontents'`` - "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a - wrapper of unmodified ``\tableofcontents``, which may itself be customized - by user loaded packages. Override if you want to generate a different table - of contents or put content between the title page and the TOC. + "tableofcontents" call. The default of + :code-tex:`r'\\sphinxtableofcontents'` is a wrapper of unmodified + :code-tex:`\\tableofcontents`, which may itself be customized by user + loaded packages. Override if you want to generate a different table of + contents or put content between the title page and the TOC. - Default: ``'\\sphinxtableofcontents'`` + Default: :code-tex:`r'\\sphinxtableofcontents'` .. versionchanged:: 1.5 - Previously the meaning of ``\tableofcontents`` itself was modified - by Sphinx. This created an incompatibility with dedicated packages - modifying it also such as "tocloft" or "etoc". + Previously the meaning of :code-tex:`\\tableofcontents` itself was + modified by Sphinx. This created an incompatibility with dedicated + packages modifying it also such as "tocloft" or "etoc". ``'transition'`` Commands used to display transitions. Override if you want to display transitions differently. - Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'`` + Default: :code-tex:`'\\n\\n\\\\bigskip\\\\hrule\\\\bigskip\\n\\n'` .. versionadded:: 1.2 .. versionchanged:: 1.6 - Remove unneeded ``{}`` after ``\\hrule``. + Remove unneeded ``{}`` formerly located after :code-tex:`\\hrule`. ``'makeindex'`` "makeindex" call, the last thing before ``\begin{document}``. With - ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use - only one column. You may have to install ``idxlayout`` LaTeX package. + :code-tex:`r'\\usepackage[columns=1]{idxlayout}\\makeindex'` the index will + use only one column. You may have to install ``idxlayout`` LaTeX package. - Default: ``'\\makeindex'`` + Default: :code-tex:`r'\\makeindex'` ``'printindex'`` "printindex" call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or - change the font. As LaTeX uses two-column mode for the index it is - often advisable to set this key to - ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column - index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail - if using a custom document class; then try the ``idxlayout`` approach - described in the documentation of the ``'makeindex'`` key). + change the font. As LaTeX uses two-column mode for the index it is often + advisable to set this key to + :code-tex:`r'\\footnotesize\\raggedright\\printindex'`. Or, to obtain a + one-column index, use :code-tex:`r'\\def\\twocolumn[#1]{#1}\\printindex'` + (this trick may fail if using a custom document class; then try the + ``idxlayout`` approach described in the documentation of the + ``'makeindex'`` key). - Default: ``'\\printindex'`` + Default: :code-tex:`r'\\printindex'` ``'fvset'`` Customization of ``fancyvrb`` LaTeX package. - The default value is ``'\\fvset{fontsize=auto}'`` which means that the + The default value is :code-tex:`r'\\fvset{fontsize=auto}'` which means that the font size will adjust correctly if a code-block ends up in a footnote. You may need to modify this if you use custom fonts: - ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like. + :code-tex:`r'\\fvset{fontsize=\\small}'` if the monospace font is Courier-like. - Default: ``'\\fvset{fontsize=auto}'`` + Default: :code-tex:`r'\\fvset{fontsize=auto}'` .. versionadded:: 1.8 .. versionchanged:: 2.0 For ``'xelatex'`` and ``'lualatex'`` defaults to - ``'\\fvset{fontsize=\\small}'`` as this + :code-tex:`r'\\fvset{fontsize=\\small}'` as this is adapted to the relative widths of the FreeFont family. .. versionchanged:: 4.0.0 Changed default for ``'pdflatex'``. Previously it was using - ``'\\fvset{fontsize=\\small}'``. + :code-tex:`r'\\fvset{fontsize=\\small}'`. .. versionchanged:: 4.1.0 Changed default for Chinese documents to - ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'`` + :code-tex:`r'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'` Keys that are set by other options and therefore should not be overridden are: @@ -683,8 +694,9 @@ The color used in the above example is available from having passed the .. versionadded:: 1.5.3 ``marginpar`` - The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value - is modified to be the closest integer multiple of the *zenkaku* width. + The :code-tex:`\\marginparwidth` LaTeX dimension. For Japanese documents, + the value is modified to be the closest integer multiple of the *zenkaku* + width. Default: ``0.5in`` @@ -821,9 +833,11 @@ The color used in the above example is available from having passed the ``verbatimcontinued`` A LaTeX macro inserted at start of continuation code lines. Its - (complicated...) default typesets a small red hook pointing to the right:: + (complicated...) default typesets a small red hook pointing to the right: + + .. code-block:: latex - \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} + \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} .. versionchanged:: 1.5 The breaking of long code lines was added at 1.4.2. The default @@ -834,12 +848,12 @@ The color used in the above example is available from having passed the Values for color keys must either: - - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something + - obey the syntax of the :code-tex:`\\definecolor` LaTeX command, e.g. something such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or ``{gray}{0.75}`` or ``{HTML}{808080}`` or ... - - or obey the syntax of the ``\colorlet`` command from package ``xcolor`` + - or obey the syntax of the :code-tex:`\\colorlet` command from package ``xcolor`` e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for this syntax. @@ -847,7 +861,7 @@ The color used in the above example is available from having passed the .. _xcolor: https://ctan.org/pkg/xcolor .. versionchanged:: 5.3.0 - Formerly only the ``\definecolor`` syntax was accepted. + Formerly only the :code-tex:`\\definecolor` syntax was accepted. ``TitleColor`` The color for titles (as configured via use of package "titlesec".) @@ -901,9 +915,10 @@ The color used in the above example is available from having passed the class. It is ignored for tables with ``nocolorrows`` class. As for the other ``'sphinxsetup'`` keys, it can also be set or modified - from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw` - directive, or also from a LaTeX environment associated to a `container - class `_ and using such ``\sphinxsetup{...}``. + from a :code-tex:`\\sphinxsetup{...}` LaTeX command inserted via the + :dudir:`raw` directive, or also from a LaTeX environment associated to a + `container class `_ and using such + :code-tex:`\\sphinxsetup{...}`. Default: ``{gray}{0.86}`` @@ -939,13 +954,13 @@ The color used in the above example is available from having passed the See :ref:`additionalcss` for its alias ``pre_padding`` and additional keys. - Default: ``\fboxsep`` + Default: :code-tex:`\\fboxsep` ``verbatimborder`` The width of the frame around :rst:dir:`code-block`\ s. See also :ref:`additionalcss` for ``pre_border-width``. - Default: ``\fboxrule`` + Default: :code-tex:`\\fboxrule` .. important:: @@ -1017,8 +1032,8 @@ The color used in the above example is available from having passed the which supports the customizability described in :ref:`additionalcss`. |notetexextras| - Some extra LaTeX code (such as ``\bfseries`` or ``\footnotesize``) - to be executed at start of the contents. + Some extra LaTeX code (such as :code-tex:`\\bfseries` or + :code-tex:`\\footnotesize`) to be executed at start of the contents. Default: empty @@ -1072,18 +1087,18 @@ The color used in the above example is available from having passed the LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number. - Default: ``\mbox{ }`` + Default: :code-tex:`\\mbox{ }` ``BeforeFootnote`` LaTeX macros inserted before the footnote mark. The default removes possible space before it (else, TeX could insert a line break there). - Default: ``\leavevmode\unskip`` + Default: :code-tex:`\\leavevmode\\unskip` .. versionadded:: 1.5 ``HeaderFamily`` - default ``\sffamily\bfseries``. Sets the font used by headings. + default :code-tex:`\\sffamily\\bfseries`. Sets the font used by headings. .. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``, @@ -1157,15 +1172,15 @@ Additional CSS-like ``'sphinxsetup'`` keys Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used -via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command +via the ``'sphinxsetup'`` interface (or the :code-tex:`\\sphinxsetup` LaTeX command inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. .. important:: Low-level LaTeX errors causing a build failure can happen if the input syntax is not respected. * In particular colors must be input as for the other color related options - previously described, i.e. either in the ``\definecolor`` syntax or via the - ``\colorlet`` syntax:: + previously described, i.e. either in the :code-tex:`\\definecolor` syntax + or via the :code-tex:`\\colorlet` syntax:: ... div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax @@ -1185,17 +1200,18 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. but not by ``xelatex`` or ``platex``. * It is allowed for such specifications to be so-called "dimensional - expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid - inputs. The expressions will be evaluated only at the typesetting time. - Be careful though if using as in these examples TeX control sequences to - double the backslash or to employ a raw Python string for the value of - the :ref:`'sphinxsetup' ` key. + expressions", e.g. :code-tex:`\\fboxsep+2pt` or + :code-tex:`0.5\\baselineskip` are valid inputs. The expressions will be + evaluated only at the typesetting time. Be careful though if using as in + these examples TeX control sequences to double the backslash or to employ + a raw Python string for the value of the :ref:`'sphinxsetup' + ` key. * As a rule, avoid inserting unneeded spaces in the key values: especially - for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also - that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX. - You must use something such as ``{\fboxsep} \fboxsep``. Or use - directly ``3pt 3pt`` which is a priori equivalent and simpler. + for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also + that :code-tex:`\\fboxsep \\fboxsep` will not be seen as space separated + in LaTeX. You must use something such as ``{\fboxsep} \fboxsep``. Or + use directly ``3pt 3pt`` which is a priori equivalent and simpler. The options are all named in a similar pattern which depends on a ``prefix``, which is then followed by an underscore, then the property name. @@ -1351,14 +1367,14 @@ forget the underscore separating the prefix from the property names. Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names`` to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`. - If ``_TeXcolor`` is set, a ``\color`` command is inserted at + If ``_TeXcolor`` is set, a :code-tex:`\\color` command is inserted at start of the directive contents; for admonitions, this happens after the heading which reproduces the admonition type. - ``_TeXextras``: if set, its value must be some LaTeX command or - commands, for example ``\itshape``. These commands will be inserted at the - start of the contents; for admonitions, this happens after the heading which - reproduces the admonition type. + commands, for example :code-tex:`\\itshape`. These commands will be + inserted at the start of the contents; for admonitions, this happens after + the heading which reproduces the admonition type. The next keys, for admonitions, :dudir:`topic`, contents_, and :dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three). @@ -1368,8 +1384,9 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and .. important:: The colored title-row is produced as a result of the Sphinx default - definitions for the various ``\sphinxstyletitle`` commands, which - employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. + definitions for the various :code-tex:`\\sphinxstyletitle` + commands, which employ the :code-tex:`\\sphinxdotitlerow` LaTeX command. + See :ref:`latex-macros`. - ``div._title-foreground-TeXcolor``: the color to be used for the icon (it applies only to the icon, not to the title of the admonition). @@ -1380,11 +1397,12 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and LaTeX ``fontawesome5`` package, which is loaded automatically if available. If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the - associated command is ``\faicon``, not ``\faIcon``) are found, or if the - ``iconpackage`` key of :ref:`'sphinxsetup' ` is set to - load some other user-chosen package, or no package at all, all the - ``title-icons`` default to empty LaTeX code. It is up to user to employ - this interface to inject the icon (or anything else) into the PDF output. + associated command is :code-tex:`\\faicon`, not :code-tex:`\\faIcon`) are + found, or if the ``iconpackage`` key of :ref:`'sphinxsetup' + ` is set to load some other user-chosen package, or no + package at all, all the ``title-icons`` default to empty LaTeX code. It is + up to user to employ this interface to inject the icon (or anything else) + into the PDF output. .. note:: @@ -1423,9 +1441,10 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or ``'xelatex'`` Sphinx includes in the preamble already - ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into - overriding a ``\footnotesize`` coming from ``pre_TeXextras``. One has - to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax. + :code-tex:`\\fvset{fontsize=\\small}` and this induces ``fancyvrb`` + into overriding a :code-tex:`\\footnotesize` coming from + ``pre_TeXextras``. One has to use + :code-tex:`pre_TeXextras=\\fvset{fontsize=\\footnotesize}` syntax. Simpler to set directly the :confval:`latex_elements` key ``'fvset'``... @@ -1530,25 +1549,26 @@ Macros with LaTeX packages. .. versionadded:: 1.8 - ``\sphinxguilabel`` + :code-tex:`\\sphinxguilabel` .. versionadded:: 3.0 - ``\sphinxkeyboard`` + :code-tex:`\\sphinxkeyboard` .. versionadded:: 6.2.0 - ``\sphinxparam``, ``\sphinxsamedocref`` + :code-tex:`\\sphinxparam`, :code-tex:`\\sphinxsamedocref` .. versionadded:: 7.1.0 - ``\sphinxparamcomma`` which defaults to a comma followed by a space and - ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line - signatures (see :confval:`maximum_signature_line_length`). It defaults - to ``\texttt{,}`` to make these end-of-line separators more distinctive. - - Signatures of Python functions are rendered as ``name(parameters)`` - or ``name[type parameters](parameters)`` (see :pep:`695`) - where the length of ```` is set to ``0pt`` by default. - This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}`` - for instance. + :code-tex:`\\sphinxparamcomma` which defaults to a comma followed by a + space and :code-tex:`\\sphinxparamcommaoneperline`. It is sed for + one-parameter-per-line signatures (see + :confval:`maximum_signature_line_length`) and defaults to + :code-tex:`\\texttt{,}`. + + Signatures of Python functions are rendered as + ``name(parameters)`` or ``name[type + parameters](parameters)`` (see :pep:`695`) where the length of + ```` is set to ``0pt`` by default. This can be changed via + :code-tex:`\\setlength{\\sphinxsignaturelistskip}{1ex}` for instance. - More text styling: @@ -1595,7 +1615,7 @@ Macros .. note:: To let this table fit on the page width in PDF output we have lied a bit. - For instance, the actual definition of ``\sphinxstylenotetitle`` is: + For instance, the actual definition of :code-tex:`\\sphinxstylenotetitle` is: .. code-block:: latex @@ -1604,90 +1624,98 @@ Macros The same remark applies to all other similar commands associated with admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not - use ``\sphinxremovefinalcolon`` as they don't need it. + use :code-tex:`\\sphinxremovefinalcolon` as they don't need it. .. versionadded:: 1.5 - These macros were formerly hard-coded as non customizable ``\texttt``, - ``\emph``, etc... + These macros were formerly hard-coded as non customizable :code-tex:`\\texttt`, + :code-tex:`\\emph`, etc... .. versionadded:: 1.6 - ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows + :code-tex:`\\sphinxstyletheadfamily` which defaults to + :code-tex:`\\sffamily` and allows multiple paragraphs in header cells of tables. .. versionadded:: 1.6.3 - ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``. + :code-tex:`\\sphinxstylecodecontinued` and + :code-tex:`\\sphinxstylecodecontinues`. .. versionadded:: 1.8 - ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``. + :code-tex:`\\sphinxstyleindexlettergroup`, + :code-tex:`\\sphinxstyleindexlettergroupDefault`. .. versionadded:: 6.2.0 - ``\sphinxstylenotetitle`` et al. The ``#1`` is the localized name of the - directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` - if this final colon is to be removed. + :code-tex:`\\sphinxstylenotetitle` et al. The ``#1`` is the localized + name of the directive, with a final colon. Wrap it as + :code-tex:`\\sphinxremovefinalcolon{#1}` if this final colon is to be + removed. .. versionadded:: 7.4.0 - Added the ``\sphinxdotitlerowwithicon`` LaTeX command. + Added the :code-tex:`\\sphinxdotitlerowwithicon` LaTeX command. .. versionchanged:: 8.1.0 - ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is + :code-tex:`\\sphinxdotitlerowwithicon` now detects automatically if an icon is associated or not with the rendered element used as first argument. - .. versionadded:: 8.1.0 - Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``. + .. versionadded:: 8.1.0 Make :code-tex:`\\sphinxdotitlerow` an alias to + :code-tex:`\\sphinxdotitlerowwithicon`. .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are - also styled using ``\sphinxdotitlerow`` (they have no default icons + also styled using :code-tex:`\\sphinxdotitlerow` (they have no default icons associated with them). -- ``\sphinxtableofcontents``: A wrapper (defined differently in +- :code-tex:`\\sphinxtableofcontents`: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard - ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed - during its expansion right before ``\tableofcontents`` itself. + :code-tex:`\\tableofcontents`. The macro + :code-tex:`\\sphinxtableofcontentshook` is executed during its expansion right + before :code-tex:`\\tableofcontents` itself. .. versionchanged:: 1.5 - Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + Formerly, the meaning of :code-tex:`\\tableofcontents` was modified by Sphinx. .. versionchanged:: 2.0 - Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly - done during loading of ``'manual'`` docclass are now executed later via - ``\sphinxtableofcontentshook``. This macro is also executed by the - ``'howto'`` docclass, but defaults to empty with it. + Hard-coded redefinitions of :code-tex:`\\l@section` and + :code-tex:`\\l@subsection` formerly done during loading of ``'manual'`` + docclass are now executed later via + :code-tex:`\\sphinxtableofcontentshook`. This macro is also executed by + the ``'howto'`` docclass, but defaults to empty with it. .. hint:: If adding to preamble the loading of ``tocloft`` package, also add to - preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset - ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it + will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection` + cancelling ``tocloft`` customization. -- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` +- :code-tex:`\\sphinxmaketitle`: Used as the default setting of the ``'maketitle'`` :confval:`latex_elements` key. Defined in the class files :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. .. versionchanged:: 1.8.3 - Formerly, ``\maketitle`` from LaTeX document class was modified by + Formerly, :code-tex:`\\maketitle` from LaTeX document class was modified by Sphinx. -- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is - defined, it gets executed at end of ``\sphinxmaketitle``, before the final - ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key - of :confval:`latex_elements` to add a custom definition of - ``\sphinxbackoftitlepage``. +- :code-tex:`\\sphinxbackoftitlepage`: For ``'manual'`` docclass, and if it is + defined, it gets executed at end of :code-tex:`\\sphinxmaketitle`, before + the final :code-tex:`\\clearpage`. Use either the ``'maketitle'`` key or + the ``'preamble'`` key of :confval:`latex_elements` to add a custom + definition of :code-tex:`\\sphinxbackoftitlepage`. .. versionadded:: 1.8.3 -- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. +- :code-tex:`\\sphinxcite`: A wrapper of standard :code-tex:`\\cite` for + citation references. .. _sphinxbox: -The ``\sphinxbox`` command -~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :code-tex:`\\sphinxbox` command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 6.2.0 -The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box" +The :code-tex:`\\sphinxbox[key=value,...]{inline text}` command can be used to "box" inline text elements with all the customizability which has been described in :ref:`additionalcss`. It is a LaTeX command with one optional argument, which is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`. @@ -1708,33 +1736,27 @@ Here is the complete list of keys. They don't use any prefix. - and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``, or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``. -This last key is specific to ``\sphinxbox`` and it means to add a ``\strut`` -so that heights and depths are equalized across various instances on the same -line with varying contents. The default is ``addstrut=false``. - -.. important:: - - Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on - feedback until then. - -The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often -satisfactory. +This last key is specific to :code-tex:`\\sphinxbox` and it means to add a +:code-tex:`\\strut` so that heights and depths are equalized across various +instances on the same line with varying contents. The default is +``addstrut=false``. The combination ``addstrut, padding-bottom=0pt, +padding-top=1pt`` is often satisfactory. Refer to :ref:`additionalcss` for important syntax information regarding the -other keys. The default -configuration uses no shadow, a border-width of ``\fboxrule``, a padding of -``\fboxsep``, circular corners with radii ``\fboxsep`` and background and -border colors as for the default rendering of code-blocks. +other keys. The default configuration uses no shadow, a border-width of +:code-tex:`\\fboxrule`, a padding of :code-tex:`\\fboxsep`, circular corners +with radii :code-tex:`\\fboxsep` and background and border colors as for the +default rendering of code-blocks. -When a ``\sphinxbox`` usage is nested within another one, it will ignore the +When a :code-tex:`\\sphinxbox` usage is nested within another one, it will ignore the options of the outer one: it first resets all options to their default state as they were prior to applying the outer box options, then it applies its own specific ones. -One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``. -The effect is cumulative, if one uses this command multiple times. Here the -options are a mandatory argument so are within curly braces, not square -brackets. +One can modify these defaults via the command +:code-tex:`\\sphinxboxsetup{key=value,...}`. The effect is cumulative, if one +uses this command multiple times. Here the options are a mandatory argument +so are within curly braces, not square brackets. Here is some example of use: @@ -1751,9 +1773,9 @@ Here is some example of use: ''', } -A utility ``\newsphinxbox`` is provided to create a new boxing macro, say -``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra -configuration: +A utility :code-tex:`\\newsphinxbox` is provided to create a new boxing macro, +say :code-tex:`\\foo` which will act exactly like :code-tex:`\\sphinxbox` but +with a given extra configuration: .. code-block:: latex @@ -1763,13 +1785,15 @@ configuration: \protected\def\sphinxguilabel#1{\foo{#1}} \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}} -Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox`` -the current configuration as set possibly mid-way in document via -``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference -is that they have an initial additional set of default extras. +Boxes rendered with :code-tex:`\\foo` obey as the ones using directly +:code-tex:`\\sphinxbox` the current configuration as set possibly mid-way in +document via :code-tex:`\\sphinxboxsetup` (from a :dudir:`raw` LaTeX mark-up), +the only difference is that they have an initial additional set of default +extras. -In the above examples, you can probably use ``\renewcommand`` syntax if you -prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then). +In the above examples, you can probably use :code-tex:`\\renewcommand` syntax +if you prefer it to :code-tex:`\\protected\\def` (with ``[1]`` in place of +``#1`` then). Environments @@ -1777,11 +1801,11 @@ 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``. + definition issues :code-tex:`\\small`, and ends with :code-tex:`\\par`. .. versionadded:: 1.5.6 - Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending - ``\par`` was lacking. + Formerly, the :code-tex:`\\small` was hardcoded in LaTeX writer and the ending + :code-tex:`\\par` was lacking. - Environments associated with admonitions: @@ -1795,7 +1819,7 @@ Environments - ``sphinxdanger``, - ``sphinxerror``. - They may be ``\renewenvironment`` + They may be :code-tex:`\\renewenvironment` 'd individually, and must then be defined with one argument (it is the heading of the notice, for example ``Warning:`` for :dudir:`warning` directive, if English is the document language). Their default definitions use either the @@ -1861,7 +1885,7 @@ Environments .. versionadded:: 1.6.6 Easier customizability of the formatting via exposed to user LaTeX macros - such as ``\sphinxVerbatimHighlightLine``. + such as :code-tex:`\\sphinxVerbatimHighlightLine`. - The bibliography uses ``sphinxthebibliography`` and the Python Module index as well as the general index both use ``sphinxtheindex``; these environments @@ -1874,36 +1898,37 @@ Environments Miscellany ~~~~~~~~~~ -- Every text paragraph in document body starts with ``\sphinxAtStartPar``. +- Every text paragraph in document body starts with :code-tex:`\\sphinxAtStartPar`. Currently, this is used to insert a zero width horizontal skip which is a trick to allow TeX hyphenation of the first word of a paragraph in a narrow context (like a table cell). For ``'lualatex'`` which - does not need the trick, the ``\sphinxAtStartPar`` does nothing. + does not need the trick, the :code-tex:`\\sphinxAtStartPar` does nothing. .. versionadded:: 3.5.0 - The section, subsection, ... headings are set using *titlesec*'s - ``\titleformat`` command. + :code-tex:`\\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``. + *fncychap*'s commands :code-tex:`\\ChNameVar`, :code-tex:`\\ChNumVar`, + :code-tex:`\\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. - The :dudir:`role` directive allows to mark inline text with class arguments. - This is handled in LaTeX output via the ``\DUrole`` dispatcher command `as - in Docutils `_. Object signatures also use ``\DUrole`` for - some components, with one or two-letters class names as in HTML output. + This is handled in LaTeX output via the :code-tex:`\\DUrole` dispatcher + command `as in Docutils `_. Object signatures also use + :code-tex:`\\DUrole` for some components, with one or two-letters class + names as in HTML output. .. versionchanged:: 8.1.0 When multiple classes are injected via a a custom role, the LaTeX output - uses nested ``\DUrole``'s as in the `Docutils documentation - `_. Formerly it used a single ``\DUrole`` with comma - separated classes, making the LaTeX customization more arduous. + uses nested :code-tex:`\\DUrole`'s as in the `Docutils documentation + `_. Formerly it used a single :code-tex:`\\DUrole` with + comma separated classes, making the LaTeX customization more arduous. .. _classarguments: https://docutils.sourceforge.io/docs/user/latex.html#custom-interpreted-text-roles diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5ffe2ea4a38..8ae9a0cc55a 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2788,7 +2788,8 @@ These options influence LaTeX output. * :code-py:`'uplatex'` -- upLaTeX (default if :confval:`language` is :code-py:`'ja'`) - .. caution:: + .. important:: + ``'pdflatex'``\ 's support for Unicode characters is limited. If your project uses Unicode characters, setting the engine to ``'xelatex'`` or ``'lualatex'`` @@ -2800,10 +2801,10 @@ These options influence LaTeX output. .. note:: - Sphinx 2.0 adds support to ``'pdflatex'`` in Latin language document of - occasional Cyrillic or Greek letters or words. - This is not automatic, see the discussion - of the ``'fontenc'`` key in :confval:`latex_elements` . + Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or + words in documents using a Latin language and ``'pdflatex'``. To enable + this, the :ref:`fontenc` key of :ref:`latex_elements + ` must be used appropriately. .. note:: @@ -2813,23 +2814,24 @@ These options influence LaTeX output. the only comprehensive solution (as far as we know) is to use ``'xelatex'`` or ``'lualatex'`` *and* to add ``r'\usepackage{unicode-math}'`` - (e.g. via the :confval:`latex_elements` ``'preamble'`` key). + (e.g. via the :ref:`preamble` key of :ref:`latex_elements + `). You may prefer ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode literal such as ``α`` (U+03B1) as-is in output, rather than being rendered as :math:`\alpha`. .. versionchanged:: 2.1.0 - Use ``xelatex`` (and LaTeX package ``xeCJK``) + Use ``'xelatex'`` (and LaTeX package ``xeCJK``) by default for Chinese documents. .. versionchanged:: 2.2.1 - Use ``xelatex`` by default for Greek documents. + Use ``'xelatex'`` by default for Greek documents. .. versionchanged:: 2.3 - Add ``uplatex`` support. + Add ``'uplatex'`` support. .. versionchanged:: 4.0 - Use ``uplatex`` by default for Japanese documents. + Use ``'uplatex'`` by default for Japanese documents. .. confval:: latex_documents :type: :code-py:`Sequence[tuple[str, str, str, str, str, bool]]` @@ -2899,16 +2901,16 @@ These options influence LaTeX output. :type: :code-py:`'part' | 'chapter' | 'section'` :default: :code-py:`None` - This value determines the topmost sectioning unit. - By default, the topmost sectioning unit is switched by documentclass: - ``section`` is used if documentclass will be ``howto``, - otherwise ``chapter`` is used be used. + This value determines the topmost sectioning unit. The default setting is + ``'section'`` if :confval:`latex_theme` is ``'howto'``, and ``'chapter'`` + if it is ``'manual'``. The alternative in both cases is to specify + ``'part'``, which means that LaTeX document will use the :code-tex:`\\part` + command. - Note that if LaTeX uses :code-tex:`\\part` command, - then the numbering of sectioning units one level deep gets off-sync - with HTML numbering, - because LaTeX numbers :code-tex:`\\chapter` continuously - (or :code-tex:`\\section` for ``howto``). + In that case the numbering of sectioning units one level deep gets off-sync + with HTML numbering, as by default LaTeX does not reset + :code-tex:`\\chapter` numbering (or :code-tex:`\\section` for ``'howto'`` + theme) when encountering :code-tex:`\\part` command. .. versionadded:: 1.4 @@ -3107,7 +3109,7 @@ These options influence LaTeX output. Use Xindy_ to prepare the index of general terms. By default, the LaTeX builder uses :program:`makeindex` for preparing the index of general terms . - This means that words with UTF-8 characters will be + Using Xindy_ means that words with UTF-8 characters will be ordered correctly for the :confval:`language`. .. _Xindy: https://xindy.sourceforge.net/ @@ -3131,7 +3133,7 @@ These options influence LaTeX output. for using :code-py:`'pdflatex'` engine with Cyrillic scripts. With both :code-py:`'pdflatex'` and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, - even with diacritics. + even those having diacritics. .. versionadded:: 1.8 @@ -3167,12 +3169,9 @@ These options influence LaTeX output. A list of file names, relative to the :term:`configuration directory`, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn't copy automatically, - e.g. if they are referenced in custom LaTeX added in ``latex_elements``. + or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via ``.. image::``) - are copied automatically. - - You have to make sure yourself that the filenames don't collide with those - of any automatically copied files. + are copied automatically and should not be listed there. .. attention:: Filenames with the ``.tex`` extension will be automatically From 3d49941484ef4dbceb155be0aedb09e49b896cd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Fri, 23 Aug 2024 18:15:40 +0200 Subject: [PATCH 12/12] LaTeX: two lines lost in previous commit (docs) (#12819) --- doc/latex.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index c53e25fcf40..96ae4ace1a4 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -174,7 +174,7 @@ Keys that you may want to override include: .. _fontpkg: ``'fontpkg'`` - Font package inclusion. The default is:: + Font package inclusion. The default with ``'pdflatex'`` is:: r"""\usepackage{tgtermes} \usepackage{tgheros} @@ -194,6 +194,7 @@ Keys that you may want to override include: .. versionchanged:: 2.0 Incorporates some font substitution commands to help support occasional Greek or Cyrillic in a document using ``'pdflatex'`` engine. + At 4.0.0 these commands were moved to the ``'fontsubstitution'`` key. .. versionchanged:: 4.0.0 The default font setting was changed. As shown above it still uses