Merge branch 'stable'

CHANGES

@@ -183,6 +183,8 @@ Bugs fixed
 * #1565, #2229: Revert new warning; the new warning will be triggered from version 1.4 on.
 * #2329: Refresh environment forcely if source directory has changed.
 * #2019: Fix the domain objects in search result are not escaped
+* #2358: Fix user-preamble could not override the tocdepth definition.
+* #2358: Redece tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel.
 
 Release 1.3.5 (released Jan 24, 2016)
 =====================================

doc/markup/toctree.rst

@@ -223,11 +223,8 @@ The special document names (and pages generated for them) are:
 
 .. rubric:: Footnotes
 
-.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
+.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
-       whole table of contents will always be presented at the begin of the
+       directive in the document.
-       document, and its depth is controlled by the ``tocdepth`` counter, which
-       you can reset in your :confval:`latex_preamble` config value using
-       e.g. ``\setcounter{tocdepth}{2}``.
 
 .. [#] A note on available globbing syntax: you can use the standard shell
        constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that

sphinx/writers/latex.py

@@ -51,6 +51,7 @@ HEADER = r'''%% Generated by Sphinx.
 %(contentsname)s
 %(numfig_format)s
 %(pageautorefname)s
+%(tocdepth)s
 %(preamble)s
 
 \title{%(title)s}
@@ -59,7 +60,6 @@ HEADER = r'''%% Generated by Sphinx.
 \author{%(author)s}
 \newcommand{\sphinxlogo}{%(logo)s}
 \renewcommand{\releasename}{%(releasename)s}
-%(tocdepth)s
 %(makeindex)s
 '''
 
@@ -331,6 +331,15 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.remember_multirow = {}
         self.remember_multirowcol = {}
 
+        # determine top section level
+        if document.settings.docclass == 'howto':
+            self.top_sectionlevel = 2
+        else:
+            if builder.config.latex_use_parts:
+                self.top_sectionlevel = 0
+            else:
+                self.top_sectionlevel = 1
+
         # sort out some elements
         papersize = builder.config.latex_paper_size + 'paper'
         if papersize == 'paper':  # e.g. command line "-D latex_paper_size="
@@ -399,12 +408,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.elements['classoptions'] += ',' + \
                                              self.elements['extraclassoptions']
         if document.get('tocdepth'):
-            if document.settings.docclass == 'howto':
+            # redece tocdepth if `part` or `chapter` is used for top_sectionlevel
-                self.elements['tocdepth'] = ('\\setcounter{tocdepth}{%d}' %
+            #   tocdepth = -1: show only parts
-                                             document['tocdepth'])
+            #   tocdepth =  0: show parts and chapters
-            else:
+            #   tocdepth =  1: show parts, chapters and sections
-                self.elements['tocdepth'] = ('\\setcounter{tocdepth}{%d}' %
+            #   tocdepth =  2: show parts, chapters, sections and subsections
-                                             (document['tocdepth'] - 1))
+            #   ...
+            self.elements['tocdepth'] = ('\\setcounter{tocdepth}{%d}' %
+                                         (document['tocdepth'] + self.top_sectionlevel - 2))
         if getattr(document.settings, 'contentsname', None):
             self.elements['contentsname'] = \
                 self.babel_renewcommand('\\contentsname', document.settings.contentsname)
@@ -432,13 +443,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.pending_footnotes = []
         self.curfilestack = []
         self.handled_abbrs = set()
-        if document.settings.docclass == 'howto':
-            self.top_sectionlevel = 2
-        else:
-            if builder.config.latex_use_parts:
-                self.top_sectionlevel = 0
-            else:
-                self.top_sectionlevel = 1
         self.next_hyperlink_ids = {}
         self.next_section_ids = set()