Merge pull request #5852 from jfbu/latex_tableofcontentshook

LaTeX: move some hard-coded re-definitions to user hook for TOC

CHANGES

@@ -45,6 +45,11 @@ Incompatible changes
   block.  As a result, they are highlighted as python3 by default.
 * The order of argument for ``HTMLTranslator``, ``HTML5Translator`` and
   ``ManualPageTranslator`` are changed
+* LaTeX: hard-coded redefinitions of ``\l@section`` and ``\l@subsection``
+  formerly done during loading of ``'manual'`` docclass get executed later, at
+  time of ``\sphinxtableofcontents``.  This means that custom user definitions
+  from LaTeX preamble now get overwritten.  Use ``\sphinxtableofcontentshook``
+  to insert custom user definitions.  See :ref:`latex-macros`.
 
 Deprecated
 ----------

doc/latex.rst

@@ -365,6 +365,8 @@ Here are some macros from the package file :file:`sphinx.sty` and class files
 :file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names
 thus allowing redefinitions. Check the respective files for the defaults.
 
+.. _latex-macros:
+
 Macros
 ~~~~~~
 
@@ -390,11 +392,18 @@ Macros
   .. versionadded:: 1.6.3
      ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
 - the table of contents is typeset via ``\sphinxtableofcontents`` which is a
-  wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
-  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
+  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.
 
   .. versionchanged:: 1.5
      formerly, the meaning of ``\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.
 - a custom ``\sphinxmaketitle`` is defined in the class files
   :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
   default setting of ``'maketitle'`` :confval:`latex_elements` key.

sphinx/texinputs/sphinxhowto.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxhowto}[2018/12/22 v1.8.3 Document class (Sphinx howto)]
+\ProvidesClass{sphinxhowto}[2018/12/23 v2.0 Document class (Sphinx howto)]
 
 % 'oneside' option overriding the 'twoside' default
 \newif\if@oneside
@@ -57,15 +57,16 @@
   %\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
 }
 
-\newcommand{\sphinxtableofcontents}{
+\newcommand{\sphinxtableofcontents}{%
   \begingroup
-    \parskip = 0mm
+    \parskip \z@skip
+    \sphinxtableofcontentshook
     \tableofcontents
   \endgroup
-  \rule{\textwidth}{1pt}
-  \vspace{12pt}
+  \noindent\rule{\textwidth}{1pt}\par
+  \vspace{12pt}%
 }  
-
+\newcommand\sphinxtableofcontentshook{}
 \pagenumbering{arabic}
 
 % Fix the bibliography environment to add an entry to the Table of

sphinx/texinputs/sphinxmanual.cls

@@ -3,7 +3,7 @@
 %
 
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{sphinxmanual}[2018/12/22 v1.8.3 Document class (Sphinx manual)]
+\ProvidesClass{sphinxmanual}[2018/12/23 v2.0 Document class (Sphinx manual)]
 
 % chapters starting at odd pages (overridden by 'openany' document option)
 \PassOptionsToClass{openright}{\sphinxdocclass}
@@ -79,6 +79,7 @@
   \pagenumbering{roman}%
   \begingroup
     \parskip \z@skip
+    \sphinxtableofcontentshook
     \tableofcontents
   \endgroup
   % before resetting page counter, let's do the right thing.
@@ -89,8 +90,10 @@
 % This is needed to get the width of the section # area wide enough in the
 % library reference.  Doing it here keeps it the same for all the manuals.
 %
-\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}
-\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}
+\newcommand{\sphinxtableofcontentshook}{%
+  \renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}}%
+  \renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}}%
+}
 
 % Fix the bibliography environment to add an entry to the Table of
 % Contents.