Make LaTeX obey numfig_secnum_depth for figures, tables, code-blocks

Notes:

- also fixes #4314

- although numbering of figures, tables and code-blocks will be same as
  in html, due to issue #4318 the numbering of enclosing sectioning units
  themselves may go deeper in html than PDF via latex. But this commit
  makes sure numbering goes to minimal depth needed by numfig_secnum_depth

doc/config.rst

@@ -341,20 +341,19 @@ General configuration
      starting at ``1``.
    - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x``
      the section number (top level sectioning; no ``x.`` if no section).
-     This naturally applies only if  section numbering has been activated via
+     This naturally applies only if section numbering has been activated via
      the ``:numbered:`` option of the :rst:dir:`toctree` directive.
    - ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in
      a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a
      section and ``1``, ``2``, ... if not in any top level section.)
    - etc...
 
-   .. note::
-
-      The LaTeX builder currently ignores this configuration setting. It will
-      obey it at Sphinx 1.7.
-
    .. versionadded:: 1.3
 
+   .. versionchanged:: 1.7
+      The LaTeX builder obeys this setting (if :confval:`numfig` is set to
+      ``True``).
+
 .. confval:: tls_verify
 
    If true, Sphinx verifies server certifications.  Default is ``True``.

sphinx/texinputs/sphinx.sty

@@ -183,7 +183,7 @@
 % control caption around literal-block
 \RequirePackage{capt-of}
 \RequirePackage{needspace}
-
+\RequirePackage{remreset}% provides \@removefromreset
 % to make pdf with correct encoded bookmarks in Japanese
 % this should precede the hyperref package
 \ifx\kanjiskip\@undefined
@@ -247,7 +247,9 @@
 \fi
 
 \DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
-
+\DeclareStringOption[-1]{numfigreset}
+\DeclareBoolOption[false]{nonumfigreset}
+% \DeclareBoolOption[false]{usespart}% not used
 % dimensions, we declare the \dimen registers here.
 \newdimen\sphinxverbatimsep
 \newdimen\sphinxverbatimborder
@@ -349,6 +351,8 @@
 \ProcessKeyvalOptions*
 % don't allow use of maxlistdepth via \sphinxsetup.
 \DisableKeyvalOption{sphinx}{maxlistdepth}
+\DisableKeyvalOption{sphinx}{numfigreset}
+\DisableKeyvalOption{sphinx}{nonumfigreset}
 % user interface: options can be changed midway in a document!
 \newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}
 
@@ -657,6 +661,7 @@
   {\abovecaptionskip\smallskipamount
    \belowcaptionskip\smallskipamount}
 
+
 %% FOOTNOTES
 %
 % Support large numbered footnotes in minipage
@@ -665,6 +670,87 @@
 \def\thempfootnote{\arabic{mpfootnote}}
 
 
+%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
+\ltx@ifundefined{c@chapter}
+   {\newcounter{literalblock}}%
+   {\newcounter{literalblock}[chapter]%
+    \def\theliteralblock{\ifnum\c@chapter>\z@\arabic{chapter}.\fi
+                         \arabic{literalblock}}%
+    }%
+\ifspx@opt@nonumfigreset
+    \ltx@ifundefined{c@chapter}{}{%
+      \@removefromreset{figure}{chapter}%
+      \@removefromreset{table}{chapter}%
+      \@removefromreset{literalblock}{chapter}%
+    }%
+    \def\thefigure{\arabic{figure}}%
+    \def\thetable {\arabic{table}}%
+    \def\theliteralblock{\arabic{literalblock}}%
+    %\let\theHliteralblock\theliteralblock
+\else
+\let\spx@preAthefigure\@empty
+\let\spx@preBthefigure\@empty
+% \ifspx@opt@usespart  % <-- LaTeX writer could pass such a 'usespart' boolean
+%                      %     as sphinx.sty package option
+% If document uses \part, (triggered in Sphinx by latex_toplevel_sectioning)
+% LaTeX core per default does not reset chapter or section
+% counters at each part.
+% But if we modify this, we need to redefine \thechapter, \thesection to
+% include the part number and this will cause problems in table of contents
+% because of too wide numbering. Simplest is to do nothing.
+% \fi
+\ifnum\spx@opt@numfigreset>0
+    \ltx@ifundefined{c@chapter}
+      {}
+      {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}.}%
+       \g@addto@macro\spx@preBthefigure{\fi}}%
+\fi
+\ifnum\spx@opt@numfigreset>1
+    \@addtoreset{figure}{section}%
+    \@addtoreset{table}{section}%
+    \@addtoreset{literalblock}{section}%
+    \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}.}%
+    \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>2
+    \@addtoreset{figure}{subsection}%
+    \@addtoreset{table}{subsection}%
+    \@addtoreset{literalblock}{subsection}%
+    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}.}%
+    \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>3
+    \@addtoreset{figure}{subsubsection}%
+    \@addtoreset{table}{subsubsection}%
+    \@addtoreset{literalblock}{subsubsection}%
+    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}.}%
+    \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>4
+    \@addtoreset{figure}{paragraph}%
+    \@addtoreset{table}{paragraph}%
+    \@addtoreset{literalblock}{paragraph}%
+    \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}.}%
+    \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\ifnum\spx@opt@numfigreset>5
+    \@addtoreset{figure}{subparagraph}%
+    \@addtoreset{table}{subparagraph}%
+    \@addtoreset{literalblock}{subparagraph}%
+    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}.}%
+    \g@addto@macro\spx@preBthefigure{\fi}%
+\fi
+\expandafter\g@addto@macro
+\expandafter\spx@preAthefigure\expandafter{\spx@preBthefigure}%
+\let\thefigure\spx@preAthefigure
+\let\thetable\spx@preAthefigure
+\let\theliteralblock\spx@preAthefigure
+\g@addto@macro\thefigure{\arabic{figure}}%
+\g@addto@macro\thetable{\arabic{table}}%
+\g@addto@macro\theliteralblock{\arabic{literalblock}}%
+\fi
+
+
 %% LITERAL BLOCKS
 %
 % Based on use of "fancyvrb.sty"'s Verbatim.
@@ -680,15 +766,6 @@
 \let\endOriginalVerbatim\endVerbatim
 
 % for captions of literal blocks
-% also define `\theH...` macros for hyperref
-\newcounter{literalblock}
-\ltx@ifundefined{c@chapter}
-  {\@addtoreset{literalblock}{section}
-  \def\theliteralblock {\ifnum\c@section>\z@ \thesection.\fi\arabic{literalblock}}
-  \def\theHliteralblock {\theHsection.\arabic{literalblock}}}
-  {\@addtoreset{literalblock}{chapter}
-  \def\theliteralblock {\ifnum\c@chapter>\z@ \thechapter.\fi\arabic{literalblock}}
-  \def\theHliteralblock {\theHchapter.\arabic{literalblock}}}
 % at start of caption title
 \newcommand*{\fnum@literalblock}{\literalblockname\nobreakspace\theliteralblock}
 % this will be overwritten in document preamble by Babel translation

sphinx/writers/latex.py

@@ -48,7 +48,6 @@ BEGIN_DOC = r'''
 
 
 URI_SCHEMES = ('mailto:', 'http:', 'https:', 'ftp:')
-SECNUMDEPTH = 3
 LATEXSECTIONNAMES = ["part", "chapter", "section", "subsection",
                      "subsubsection", "paragraph", "subparagraph"]
 
@@ -504,6 +503,8 @@ def rstdim_to_latexdim(width_str):
 
 class LaTeXTranslator(nodes.NodeVisitor):
 
+    secnumdepth = 2  # legacy sphinxhowto.cls uses this, whereas article.cls
+    # default is originally 3. For book/report, 2 is already LaTeX default.
     ignore_missing_images = False
 
     # sphinx specific document classes
@@ -581,6 +582,24 @@ class LaTeXTranslator(nodes.NodeVisitor):
         else:
             self.elements['date'] = format_date(builder.config.today_fmt or _('%b %d, %Y'),  # type: ignore  # NOQA
                                                 language=builder.config.language)
+
+        if builder.config.numfig:
+            self.numfig_secnum_depth = builder.config.numfig_secnum_depth
+            if self.numfig_secnum_depth > 0:  # default is 1
+                # numfig_secnum_depth as passed to sphinx.sty indices same names as in
+                # LATEXSECTIONNAMES but with -1 for part, 0 for chapter, 1 for section...
+                if len(self.sectionnames) < 7 and self.top_sectionlevel > 0:
+                    self.numfig_secnum_depth += self.top_sectionlevel
+                else:
+                    self.numfig_secnum_depth += self.top_sectionlevel - 1
+                if self.numfig_secnum_depth >= len(self.sectionnames):
+                    self.numfig_secnum_depth = len(self.sectionnames) - 1
+                # if passed key value is < 1 LaTeX will act as if 0; see sphinx.sty
+                self.elements['sphinxpkgoptions'] += \
+                    (',numfigreset=%s' % self.numfig_secnum_depth)
+            else:
+                self.elements['sphinxpkgoptions'] += ',nonumfigreset'
+
         if builder.config.latex_logo:
             # no need for \\noindent here, used in flushright
             self.elements['logo'] = '\\sphinxincludegraphics{%s}\\par' % \
@@ -637,6 +656,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
                     return '\\usepackage{%s}' % (packagename,)
             usepackages = (declare_package(*p) for p in builder.usepackages)
             self.elements['usepackages'] += "\n".join(usepackages)
+
+        minsecnumdepth = self.secnumdepth  # 2 from legacy sphinx manual/howto
         if document.get('tocdepth'):
             # reduce tocdepth if `part` or `chapter` is used for top_sectionlevel
             #   tocdepth = -1: show only parts
@@ -653,9 +674,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 tocdepth = 5
 
             self.elements['tocdepth'] = '\\setcounter{tocdepth}{%d}' % tocdepth
-            if tocdepth >= SECNUMDEPTH:
+            minsecnumdepth = max(minsecnumdepth, tocdepth)
-                # Increase secnumdepth if tocdepth is deeper than default SECNUMDEPTH
+
-                self.elements['secnumdepth'] = '\\setcounter{secnumdepth}{%d}' % tocdepth
+        if builder.config.numfig and (builder.config.numfig_secnum_depth > 0):
+            minsecnumdepth = max(minsecnumdepth, self.numfig_secnum_depth - 1)
+
+        if minsecnumdepth > self.secnumdepth:
+            self.elements['secnumdepth'] = '\\setcounter{secnumdepth}{%d}' %\
+                                           minsecnumdepth
 
         if getattr(document.settings, 'contentsname', None):
             self.elements['contentsname'] = \