From 110c2b0dbca11861b2451a8a91f4bc60ee7d7a6a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 24 Feb 2016 01:30:17 +0900 Subject: [PATCH] Fix #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of LaTeX document. --- CHANGES | 2 ++ doc/config.rst | 12 +++++++++++ sphinx/builders/latex.py | 16 ++++++++++++++ sphinx/config.py | 2 ++ sphinx/writers/latex.py | 14 ++++++++----- tests/test_build_latex.py | 44 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 85 insertions(+), 5 deletions(-) diff --git a/CHANGES b/CHANGES index 6de3570dc..52cedbefd 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 -------------- @@ -17,6 +18,7 @@ Features added * Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of `menuselection` roles. * Define ``\internalreference`` macro to redefine the style of references * #2301: Texts in the classic html theme should be hyphenated. +* #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 40ee674cd..9506657da 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1459,6 +1459,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: @@ -1466,6 +1475,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 ac94c5d03..44fd61e8e 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -206,7 +206,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 73ebf4b0e..a2a308033 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 ea1468c2e..66cc4281b 100644 --- a/tests/test_build_latex.py +++ b/tests/test_build_latex.py @@ -615,3 +615,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