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.
 - the ``\maketitle`` command is redefined by the class files
   :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
 - the citation reference is typeset via ``\sphinxcite`` which is a wrapper

sphinx/texinputs/sphinxhowto.cls

@@ -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

@@ -77,6 +77,7 @@
   \pagenumbering{roman}%
   \begingroup
     \parskip \z@skip
+    \sphinxtableofcontentshook
     \tableofcontents
   \endgroup
   % before resetting page counter, let's do the right thing.
@@ -87,8 +88,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.