Merge branch '2327_toplevel_sectioning'

CHANGES

@@ -3,6 +3,7 @@ Release 1.4 alpha2 (in development)
 
 Incompatible changes
 --------------------
+* #2327: `latex_use_parts` is deprecated now. Use `latex_toplevel_sectioning` instead.
 
 Features added
 --------------
@@ -20,6 +21,7 @@ Features added
 * #2355: Define ``\termref`` macro to redefine the style of ``term`` roles.
 * Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental)
 * #2229: Fix no warning is given for unknown options
+* #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of LaTeX document.
 
 Bugs fixed
 ----------

doc/config.rst

@@ -1479,6 +1479,15 @@ These options influence LaTeX output.
    configuration directory) that is the logo of the docs.  It is placed at the
    top of the title page.  Default: ``None``.
 
+.. confval:: latex_toplevel_sectioning
+
+   This value determines the topmost sectioning unit. It should be chosen from
+   ``part``, ``chapter`` or ``section``. The default is ``None``; the topmost
+   sectioning unit is switched by documentclass. ``section`` is used if
+   documentclass will be ``howto``, otherwise ``chapter`` will be used.
+
+   .. versionadded:: 1.4
+
 .. confval:: latex_use_parts
 
    If true, the topmost sectioning unit is parts, else it is chapters.  Default:
@@ -1486,6 +1495,9 @@ These options influence LaTeX output.
 
    .. versionadded:: 0.3
 
+   .. deprecated:: 1.4
+      Use :confval:`latex_toplevel_sectioning`.
+
 .. confval:: latex_appendices
 
    A list of document names to append as an appendix to all manuals.

sphinx/builders/latex.py

@@ -11,6 +11,7 @@
 
 import os
 from os import path
+import warnings
 
 from six import iteritems
 from docutils import nodes
@@ -43,6 +44,21 @@ class LaTeXBuilder(Builder):
         self.docnames = []
         self.document_data = []
         texescape.init()
+        self.check_options()
+
+    def check_options(self):
+        if self.config.latex_toplevel_sectioning not in (None, 'part', 'chapter', 'section'):
+            self.warn('invalid latex_toplevel_sectioning, ignored: %s' %
+                      self.config.latex_top_sectionlevel)
+            self.config.latex_top_sectionlevel = None
+
+        if self.config.latex_use_parts:
+            warnings.warn('latex_use_parts will be removed at Sphinx-1.5. '
+                          'Use latex_toplevel_sectioning instead.',
+                          DeprecationWarning)
+
+            if self.config.latex_toplevel_sectioning:
+                self.warn('latex_use_parts conflicts with latex_toplevel_sectioning, ignored.')
 
     def get_outdated_docs(self):
         return 'all documents'  # for now

sphinx/config.py

@@ -207,7 +207,9 @@ class Config(object):
                            None),
         latex_logo = (None, None, string_classes),
         latex_appendices = ([], None),
+        # now deprecated - use latex_toplevel_sectioning
         latex_use_parts = (False, None),
+        latex_toplevel_sectioning = (None, None, [str]),
         latex_use_modindex = (True, None),  # deprecated
         latex_domain_indices = (True, None, [list]),
         latex_show_urls = ('no', None),

sphinx/writers/latex.py

@@ -332,13 +332,17 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.remember_multirowcol = {}
 
         # determine top section level
-        if document.settings.docclass == 'howto':
+        if builder.config.latex_toplevel_sectioning:
-            self.top_sectionlevel = 2
+            self.top_sectionlevel = \
+                self.sectionnames.index(builder.config.latex_toplevel_sectioning)
         else:
-            if builder.config.latex_use_parts:
+            if document.settings.docclass == 'howto':
-                self.top_sectionlevel = 0
+                self.top_sectionlevel = 2
             else:
-                self.top_sectionlevel = 1
+                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'

tests/test_build_latex.py

@@ -612,3 +612,47 @@ def test_toctree_without_maxdepth(app, status, warning):
     print(status.getvalue())
     print(warning.getvalue())
     assert '\\setcounter{tocdepth}' not in result
+
+
+@with_app(buildername='latex', testroot='toctree-maxdepth',
+          confoverrides={'latex_toplevel_sectioning': None})
+def test_latex_toplevel_sectioning_is_None(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    print(result)
+    print(status.getvalue())
+    print(warning.getvalue())
+    assert '\\chapter{Foo}' in result
+
+
+@with_app(buildername='latex', testroot='toctree-maxdepth',
+          confoverrides={'latex_toplevel_sectioning': 'part'})
+def test_latex_toplevel_sectioning_is_part(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    print(result)
+    print(status.getvalue())
+    print(warning.getvalue())
+    assert '\\part{Foo}' in result
+
+
+@with_app(buildername='latex', testroot='toctree-maxdepth',
+          confoverrides={'latex_toplevel_sectioning': 'chapter'})
+def test_latex_toplevel_sectioning_is_chapter(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    print(result)
+    print(status.getvalue())
+    print(warning.getvalue())
+    assert '\\chapter{Foo}' in result
+
+
+@with_app(buildername='latex', testroot='toctree-maxdepth',
+          confoverrides={'latex_toplevel_sectioning': 'section'})
+def test_latex_toplevel_sectioning_is_section(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    print(result)
+    print(status.getvalue())
+    print(warning.getvalue())
+    assert '\\section{Foo}' in result