LaTeX: Add math_numsep support to latex builder (#12652)

Co-authored-by: Jean-François B <2589111+jfbu@users.noreply.github.com>

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 <sphinx-build --fail-on-warning>` is used.
   Instead, exit with a non-zero status if any warnings were generated

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

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.

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

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):

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(