diff --git a/CHANGES b/CHANGES index d06a81314..579bce393 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/config.rst b/doc/config.rst index 41ec68ec8..c87db8dd3 100644 --- a/doc/config.rst +++ b/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. diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 56767ab8a..f3e64bcb1 100644 --- a/sphinx/builders/latex.py +++ b/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 diff --git a/sphinx/config.py b/sphinx/config.py index 8a2cfe36f..73f442cf9 100644 --- a/sphinx/config.py +++ b/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), diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 30f5d6df3..0fd0799cf 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -332,13 +332,17 @@ class LaTeXTranslator(nodes.NodeVisitor): self.remember_multirowcol = {} # determine top section level - if document.settings.docclass == 'howto': - self.top_sectionlevel = 2 + if builder.config.latex_toplevel_sectioning: + self.top_sectionlevel = \ + self.sectionnames.index(builder.config.latex_toplevel_sectioning) else: - if builder.config.latex_use_parts: - self.top_sectionlevel = 0 + if document.settings.docclass == 'howto': + 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' diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index ee028ea32..a7a0d59e3 100644 --- a/tests/test_build_latex.py +++ b/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