Merge branch '2327_toplevel_sectioning'

This commit is contained in:
Takeshi KOMIYA 2016-03-03 20:41:17 +09:00
commit da94ca5699
6 changed files with 85 additions and 5 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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