From 0b0bbfcb5b8e5ee836a14aa80c762f0ea875ccd0 Mon Sep 17 00:00:00 2001 From: jfbu Date: Tue, 30 May 2017 21:01:52 +0200 Subject: [PATCH 1/4] Backport docutils.utils.smartquotes fixes as of r8097 This incorporates fixes from 0.14rc1 which were not in the PR #3666 merged in 1.6.1, and extra language configurations and fixes for quotes. Only active if Docutils is at 0.13.1 or earlier. --- sphinx/util/smartypants.py | 129 ++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 16 deletions(-) diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py index 2c4fe7d92..4d19e8870 100644 --- a/sphinx/util/smartypants.py +++ b/sphinx/util/smartypants.py @@ -3,8 +3,11 @@ sphinx.util.smartypants ~~~~~~~~~~~~~~~~~~~~~~~ - This code is copied from docutils’ docutils/utils/smartquotes.py - version 1.7.1 (from 2017-03-19). It should be removed in the future. + This is extracted (with minor adaptations for flake8 compliance) from + docutils’ docutils/utils/smartquotes.py as of revision 8097 (30 May 2017), + in order to backport for Sphinx usage with Docutils < 0.14 extra language + configurations and fixes. Replaces earlier smartypants version as used up + to Sphinx 1.5.6. :copyright: © 2010 Günter Milde, original `SmartyPants`_: © 2003 John Gruber @@ -20,6 +23,7 @@ .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause See the LICENSE file and the original docutils code for details. + """ from __future__ import absolute_import, unicode_literals @@ -31,6 +35,96 @@ if False: # For type annotation from typing import Iterable, Iterator, Tuple # NOQA +langquotes = {'af': u'“”‘’', + 'af-x-altquot': u'„”‚’', + 'bg': u'„“‚‘', # Bulgarian, https://bg.wikipedia.org/wiki/Кавички + 'ca': u'«»“”', + 'ca-x-altquot': u'“”‘’', + 'cs': u'„“‚‘', + 'cs-x-altquot': u'»«›‹', + 'da': u'»«›‹', + 'da-x-altquot': u'„“‚‘', + # 'da-x-altquot2': u'””’’', + 'de': u'„“‚‘', + 'de-x-altquot': u'»«›‹', + 'de-ch': u'«»‹›', + 'el': u'«»“”', + 'en': u'“”‘’', + 'en-uk-x-altquot': u'‘’“”', # Attention: " → ‘ and ' → “ ! + 'eo': u'“”‘’', + 'es': u'«»“”', + 'es-x-altquot': u'“”‘’', + 'et': u'„“‚‘', # no secondary quote listed in + 'et-x-altquot': u'«»‹›', # the sources above (wikipedia.org) + 'eu': u'«»‹›', + 'fi': u'””’’', + 'fi-x-altquot': u'»»››', + 'fr': (u'« ', u' »', u'“', u'”'), # full no-break space + 'fr-x-altquot': (u'« ', u' »', u'“', u'”'), # narrow no-break space + 'fr-ch': u'«»‹›', + 'fr-ch-x-altquot': (u'« ', u' »', u'‹ ', u' ›'), # narrow no-break space + # http://typoguide.ch/ + 'gl': u'«»“”', + 'he': u'”“»«', # Hebrew is RTL, test position: + 'he-x-altquot': u'„”‚’', # low quotation marks are opening. + # 'he-x-altquot': u'“„‘‚', # RTL: low quotation marks opening + 'hr': u'„”‘’', # http://hrvatska-tipografija.com/polunavodnici/ + 'hr-x-altquot': u'»«›‹', + 'hsb': u'„“‚‘', + 'hsb-x-altquot': u'»«›‹', + 'hu': u'„”«»', + 'is': u'„“‚‘', + 'it': u'«»“”', + 'it-ch': u'«»‹›', + 'it-x-altquot': u'“”‘’', + # 'it-x-altquot2': u'“„‘‚', # [7] in headlines + 'ja': u'「」『』', + 'lt': u'„“‚‘', + 'lv': u'„“‚‘', + 'mk': u'„“‚‘', # Macedonian, + # https://mk.wikipedia.org/wiki/Правопис_и_правоговор_на_македонскиот_јазик + 'nl': u'“”‘’', + 'nl-x-altquot': u'„”‚’', + # 'nl-x-altquot2': u'””’’', + 'nb': u'«»’’', # Norsk bokmål (canonical form 'no') + 'nn': u'«»’’', # Nynorsk [10] + 'nn-x-altquot': u'«»‘’', # [8], [10] + # 'nn-x-altquot2': u'«»«»', # [9], [10] + # 'nn-x-altquot3': u'„“‚‘', # [10] + 'no': u'«»’’', # Norsk bokmål [10] + 'no-x-altquot': u'«»‘’', # [8], [10] + # 'no-x-altquot2': u'«»«»', # [9], [10] + # 'no-x-altquot3': u'„“‚‘', # [10] + 'pl': u'„”«»', + 'pl-x-altquot': u'«»‚’', + # 'pl-x-altquot2': u'„”‚’', + # https://pl.wikipedia.org/wiki/Cudzys%C5%82%C3%B3w + 'pt': u'«»“”', + 'pt-br': u'“”‘’', + 'ro': u'„”«»', + 'ru': u'«»„“', + 'sh': u'„”‚’', # Serbo-Croatian + 'sh-x-altquot': u'»«›‹', + 'sk': u'„“‚‘', # Slovak + 'sk-x-altquot': u'»«›‹', + 'sl': u'„“‚‘', # Slovenian + 'sl-x-altquot': u'»«›‹', + 'sq': u'«»‹›', # Albanian + 'sq-x-altquot': u'“„‘‚', + 'sr': u'„”’’', + 'sr-x-altquot': u'»«›‹', + 'sv': u'””’’', + 'sv-x-altquot': u'»»››', + 'tr': u'“”‘’', + 'tr-x-altquot': u'«»‹›', + # 'tr-x-altquot2': u'“„‘‚', # [7] antiquated? + 'uk': u'«»„“', + 'uk-x-altquot': u'„“‚‘', + 'zh-cn': u'“”‘’', + 'zh-tw': u'「」『』', + } + + def educateQuotes(text, language='en'): # type: (unicode, unicode) -> unicode """ @@ -43,7 +137,10 @@ def educateQuotes(text, language='en'): """ smart = smartquotes.smartchars(language) - smart.apostrophe = u'’' + try: + apostrophe = smart.apostrophe + except: + apostrophe = u'’' # oldtext = text punct_class = r"""[!"#\$\%'()*+,-.\/:;<=>?\@\[\\\]\^_`{|}~]""" @@ -60,7 +157,8 @@ def educateQuotes(text, language='en'): text = re.sub(r"""'"(?=\w)""", smart.osquote + smart.opquote, text) # Special case for decade abbreviations (the '80s): - text = re.sub(r"""\b'(?=\d{2}s)""", smart.csquote, text) + if language.startswith('en'): # TODO similar cases in other languages? + text = re.sub(r"""'(?=\d{2}s)""", apostrophe, text, re.UNICODE) close_class = r"""[^\ \t\r\n\[\{\(\-]""" dec_dashes = r"""–|—""" @@ -81,9 +179,11 @@ def educateQuotes(text, language='en'): text = opening_single_quotes_regex.sub(r'\1' + smart.osquote, text) # In many locales, single closing quotes are different from apostrophe: - if smart.csquote != smart.apostrophe: + if smart.csquote != apostrophe: apostrophe_regex = re.compile(r"(?<=(\w|\d))'(?=\w)", re.UNICODE) - text = apostrophe_regex.sub(smart.apostrophe, text) + text = apostrophe_regex.sub(apostrophe, text) + # TODO: keep track of quoting level to recognize apostrophe in, e.g., + # "Ich fass' es nicht." closing_single_quotes_regex = re.compile(r""" (%s) @@ -140,7 +240,7 @@ def educateQuotes(text, language='en'): return text -def educate_tokens(text_tokens, attr='1', language='en'): +def educate_tokens(text_tokens, attr=smartquotes.default_smartypants_attr, language='en'): # type: (Iterable[Tuple[str, unicode]], unicode, unicode) -> Iterator """Return iterator that "educates" the items of `text_tokens`. """ @@ -167,9 +267,7 @@ def educate_tokens(text_tokens, attr='1', language='en'): do_ellipses = False do_stupefy = False - if attr == "0": # Do nothing. - pass - elif attr == "1": # Do everything, turn all options on. + if attr == "1": # Do everything, turn all options on. do_quotes = True do_backticks = 1 do_dashes = 1 @@ -266,15 +364,14 @@ def educate_tokens(text_tokens, attr='1', language='en'): if docutils_version < (0, 13, 2): - # Monkey patch the old docutils versions to fix the issue mentioned + # Monkey patch the old docutils versions to fix the issues mentioned # at https://sourceforge.net/p/docutils/bugs/313/ + # at https://sourceforge.net/p/docutils/bugs/317/ + # and more smartquotes.educateQuotes = educateQuotes - - # And the one mentioned at https://sourceforge.net/p/docutils/bugs/317/ smartquotes.educate_tokens = educate_tokens # Fix the issue with French quotes mentioned at # https://sourceforge.net/p/docutils/mailman/message/35760696/ - quotes = smartquotes.smartchars.quotes - quotes['fr'] = (u'«\u00a0', u'\u00a0»', u'“', u'”') - quotes['fr-ch'] = u'«»‹›' + # Add/fix other languages as well + smartquotes.smartchars.quotes = langquotes From 2f61be8bb7137d0f2f712b8b230d7ab93d003b6f Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 4 Jun 2017 13:54:40 +0900 Subject: [PATCH 2/4] Fix Emit wrong warnings if citation label includes hyphens (refs: #3558) --- CHANGES | 1 + sphinx/domains/std.py | 9 ++++++--- tests/roots/test-root/footnote.txt | 3 +++ tests/test_build_html.py | 16 +++++++++------- tests/test_build_html5.py | 16 +++++++++------- 5 files changed, 28 insertions(+), 17 deletions(-) diff --git a/CHANGES b/CHANGES index 5db4fc395..f84a70c4c 100644 --- a/CHANGES +++ b/CHANGES @@ -19,6 +19,7 @@ Bugs fixed * #3821: Failed to import sphinx.util.compat with docutils-0.14rc1 * #3829: sphinx-quickstart template is incomplete regarding use of alabaster * #3772: 'str object' has no attribute 'filename' +* Emit wrong warnings if citation label includes hyphens (refs: #3558) Testing -------- diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index a7a41747e..26645eed2 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -493,7 +493,7 @@ class StandardDomain(Domain): 'progoptions': {}, # (program, name) -> docname, labelid 'objects': {}, # (type, name) -> docname, labelid 'citations': {}, # name -> docname, labelid, lineno - 'citation_refs': {}, # name -> list of docnames + 'citation_refs': {}, # labelid -> list of docnames 'labels': { # labelname -> docname, labelid, sectionname 'genindex': ('genindex', '', l_('Index')), 'modindex': ('py-modindex', '', l_('Module Index')), @@ -589,8 +589,11 @@ class StandardDomain(Domain): def note_citation_refs(self, env, docname, document): # type: (BuildEnvironment, unicode, nodes.Node) -> None for name, refs in iteritems(document.citation_refs): - citation_refs = self.data['citation_refs'].setdefault(name, []) - citation_refs.append(docname) + for ref in refs: + labelid = ref.get('refid') + if labelid: + citation_refs = self.data['citation_refs'].setdefault(labelid, []) + citation_refs.append(docname) def note_labels(self, env, docname, document): # type: (BuildEnvironment, unicode, nodes.Node) -> None diff --git a/tests/roots/test-root/footnote.txt b/tests/roots/test-root/footnote.txt index dc5e0b0da..9ea8d5082 100644 --- a/tests/roots/test-root/footnote.txt +++ b/tests/roots/test-root/footnote.txt @@ -23,6 +23,7 @@ citation -------------------- [bar]_ +[baz_qux]_ footnotes in table -------------------- @@ -50,6 +51,8 @@ footenotes .. [bar] cite +.. [baz_qux] citation including underscore + .. [#] footnote in table caption .. [#] footnote in table header diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 297334f0d..b2533629d 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -422,19 +422,21 @@ def test_static_output(app): (".//li/a", "double"), ], 'footnote.html': [ - (".//a[@class='footnote-reference'][@href='#id8'][@id='id1']", r"\[1\]"), - (".//a[@class='footnote-reference'][@href='#id9'][@id='id2']", r"\[2\]"), + (".//a[@class='footnote-reference'][@href='#id9'][@id='id1']", r"\[1\]"), + (".//a[@class='footnote-reference'][@href='#id10'][@id='id2']", r"\[2\]"), (".//a[@class='footnote-reference'][@href='#foo'][@id='id3']", r"\[3\]"), (".//a[@class='reference internal'][@href='#bar'][@id='id4']", r"\[bar\]"), - (".//a[@class='footnote-reference'][@href='#id10'][@id='id5']", r"\[4\]"), - (".//a[@class='footnote-reference'][@href='#id11'][@id='id6']", r"\[5\]"), + (".//a[@class='reference internal'][@href='#baz-qux'][@id='id5']", r"\[baz_qux\]"), + (".//a[@class='footnote-reference'][@href='#id11'][@id='id6']", r"\[4\]"), + (".//a[@class='footnote-reference'][@href='#id12'][@id='id7']", r"\[5\]"), (".//a[@class='fn-backref'][@href='#id1']", r"\[1\]"), (".//a[@class='fn-backref'][@href='#id2']", r"\[2\]"), (".//a[@class='fn-backref'][@href='#id3']", r"\[3\]"), (".//a[@class='fn-backref'][@href='#id4']", r"\[bar\]"), - (".//a[@class='fn-backref'][@href='#id5']", r"\[4\]"), - (".//a[@class='fn-backref'][@href='#id6']", r"\[5\]"), - (".//a[@class='fn-backref'][@href='#id7']", r"\[6\]"), + (".//a[@class='fn-backref'][@href='#id5']", r"\[baz_qux\]"), + (".//a[@class='fn-backref'][@href='#id6']", r"\[4\]"), + (".//a[@class='fn-backref'][@href='#id7']", r"\[5\]"), + (".//a[@class='fn-backref'][@href='#id8']", r"\[6\]"), ], 'otherext.html': [ (".//h1", "Generated section"), diff --git a/tests/test_build_html5.py b/tests/test_build_html5.py index d24bac570..7fc91b9ec 100644 --- a/tests/test_build_html5.py +++ b/tests/test_build_html5.py @@ -297,19 +297,21 @@ def cached_etree_parse(): (".//li/a", "double"), ], 'footnote.html': [ - (".//a[@class='footnote-reference brackets'][@href='#id8'][@id='id1']", r"1"), - (".//a[@class='footnote-reference brackets'][@href='#id9'][@id='id2']", r"2"), + (".//a[@class='footnote-reference brackets'][@href='#id9'][@id='id1']", r"1"), + (".//a[@class='footnote-reference brackets'][@href='#id10'][@id='id2']", r"2"), (".//a[@class='footnote-reference brackets'][@href='#foo'][@id='id3']", r"3"), (".//a[@class='reference internal'][@href='#bar'][@id='id4']", r"\[bar\]"), - (".//a[@class='footnote-reference brackets'][@href='#id10'][@id='id5']", r"4"), - (".//a[@class='footnote-reference brackets'][@href='#id11'][@id='id6']", r"5"), + (".//a[@class='reference internal'][@href='#baz-qux'][@id='id5']", r"\[baz_qux\]"), + (".//a[@class='footnote-reference brackets'][@href='#id11'][@id='id6']", r"4"), + (".//a[@class='footnote-reference brackets'][@href='#id12'][@id='id7']", r"5"), (".//a[@class='fn-backref'][@href='#id1']", r"1"), (".//a[@class='fn-backref'][@href='#id2']", r"2"), (".//a[@class='fn-backref'][@href='#id3']", r"3"), (".//a[@class='fn-backref'][@href='#id4']", r"bar"), - (".//a[@class='fn-backref'][@href='#id5']", r"4"), - (".//a[@class='fn-backref'][@href='#id6']", r"5"), - (".//a[@class='fn-backref'][@href='#id7']", r"6"), + (".//a[@class='fn-backref'][@href='#id5']", r"baz_qux"), + (".//a[@class='fn-backref'][@href='#id6']", r"4"), + (".//a[@class='fn-backref'][@href='#id7']", r"5"), + (".//a[@class='fn-backref'][@href='#id8']", r"6"), ], 'otherext.html': [ (".//h1", "Generated section"), From 17c366659aebc88ee2681f31157a4501a0b26e6c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 4 Jun 2017 13:56:15 +0900 Subject: [PATCH 3/4] Update CHANGES --- CHANGES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index f84a70c4c..38878cd07 100644 --- a/CHANGES +++ b/CHANGES @@ -19,7 +19,7 @@ Bugs fixed * #3821: Failed to import sphinx.util.compat with docutils-0.14rc1 * #3829: sphinx-quickstart template is incomplete regarding use of alabaster * #3772: 'str object' has no attribute 'filename' -* Emit wrong warnings if citation label includes hyphens (refs: #3558) +* Emit wrong warnings if citation label includes hyphens (refs: #3565) Testing -------- From bd8c7e14101ee9feef5e8d432470a2983be23709 Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 5 Jun 2017 12:11:41 +0200 Subject: [PATCH 4/4] Make the latex docs more concise --- doc/latex.rst | 389 ++++++++++++++++++++++---------------------------- 1 file changed, 173 insertions(+), 216 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 2f68899f8..644fd5e06 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -33,167 +33,143 @@ The *latex* target does not benefit from pre-prepared themes like the Basic customization ------------------- -It is available from ``conf.py`` via usage of the -:ref:`latex-options` as described in :doc:`config` (backslashes must be doubled -in Python string literals to reach latex.) For example:: +It is achieved via usage of the +:ref:`latex-options` as described in :doc:`config`. For example:: - # inside conf.py - latex_engine = 'xelatex' - latex_elements = { - 'fontenc': '\\usepackage{fontspec}', - 'fontpkg': '''\ - \\setmainfont{DejaVu Serif} - \\setsansfont{DejaVu Sans} - \\setmonofont{DejaVu Sans Mono}''', - 'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}', - 'preamble': '''\ - \\usepackage[titles]{tocloft} - \\cftsetpnumwidth {1.25cm}\\cftsetrmarg{1.5cm} - \\setlength{\\cftchapnumwidth}{0.75cm} - \\setlength{\\cftsecindent}{\\cftchapnumwidth} - \\setlength{\\cftsecnumwidth}{1.25cm}''', - 'fncychap': '\\usepackage[Bjornstrup]{fncychap}', - 'printindex': '\\footnotesize\\raggedright\\printindex', - } - latex_show_urls = 'footnote' + # inside conf.py + latex_engine = 'xelatex' + latex_elements = { + 'fontpkg': r''' + \setmainfont{DejaVu Serif} + \setsansfont{DejaVu Sans} + \setmonofont{DejaVu Sans Mono} + ''', + 'preamble': r''' + \usepackage[titles]{tocloft} + \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm} + \setlength{\cftchapnumwidth}{0.75cm} + \setlength{\cftsecindent}{\cftchapnumwidth} + \setlength{\cftsecnumwidth}{1.25cm} + ''', + 'fncychap': r'\usepackage[Bjornstrup]{fncychap}', + 'printindex': r'\footnotesize\raggedright\printindex', + } + latex_show_urls = 'footnote' .. the above was tested on Sphinx's own 1.5a2 documentation with good effect! .. highlight:: latex -More advanced customization will be obtained via insertion into the LaTeX -preamble of relevant ``\renewcommand``, ``\renewenvironment``, ``\setlength``, -or ``\definecolor`` commands. The ``'preamble'`` key of -:confval:`latex_elements` will serve for inserting these commands. If they are -numerous, it may prove more convenient to assemble them into a specialized -file :file:`mystyle.tex` and then use:: +If the size of the ``'preamble'`` contents become inconvenient, one may put +all needed macros into some file :file:`mystyle.tex` of the project source +repertory, and get LaTeX to import it at run time:: - 'preamble': r'\makeatletter\input{mystyle.tex}\makeatother', + 'preamble': r'\input{mystyle.tex}', + # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty + 'preamble': r'\usepackage{mystyle}', -or, better, to set up a style file -:file:`mystyle.sty` which can then be loaded via:: +It is needed to set appropriately :confval:`latex_additional_files`, for +example:: - 'preamble': r'\usepackage{mystyle}', - -The :ref:`build configuration file ` file for the project needs -to have its variable :confval:`latex_additional_files` appropriately -configured, for example:: - - latex_additional_files = ["mystyle.sty"] + latex_additional_files = ["mystyle.tex"] .. _latexsphinxsetup: -The Sphinx LaTeX style package options --------------------------------------- +The LaTeX style file options +---------------------------- -The ``'sphinxsetup'`` key to :confval:`latex_elements` provides a -more convenient interface to various style parameters. It is a comma separated -string of ``key=value`` instructions:: +The sphinxsetup interface +~~~~~~~~~~~~~~~~~~~~~~~~~ - key1=value1,key2=value2, ... +The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient +interface to the package options of the Sphinx style file:: -- if a key is repeated, it is its last occurence which is used -- spaces around the commas and equal signs are ignored + latex_elements = { + 'sphinxsetup': 'key1=value1, key2=value2, ...', + } -If non-empty, it will be passed as argument to the ``\sphinxsetup`` command:: +- some values may be LaTeX macros, then the backslashes must be + Python-escaped, or the whole must be a Python raw string, +- LaTeX boolean keys require *lowercase* ``true`` or ``false`` values, +- spaces around the commas and equal signs are ignored, spaces inside LaTeX + macros may be significant. - \usepackage{sphinx} - \sphinxsetup{key1=value1,key2=value2,...} +If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro +inside the document preamble, like this:: + + \usepackage{sphinx} + \sphinxsetup{key1=value1, key2=value2,...} .. versionadded:: 1.5 +It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro +directly into the body of the document, via the help of the :rst:dir:`raw` +directive. This is what is done for this documentation, for local styling +of this chapter in the PDF output:: + + .. raw:: latex + + \begingroup + \sphinxsetup{% + verbatimwithframe=false, + VerbatimColor={named}{OldLace}, + TitleColor={named}{DarkGoldenrod}, + hintBorderColor={named}{LightCoral}, + attentionborder=3pt, + attentionBorderColor={named}{Crimson}, + attentionBgColor={named}{FloralWhite}, + noteborder=2pt, + noteBorderColor={named}{Olive}, + cautionborder=3pt, + cautionBorderColor={named}{Cyan}, + cautionBgColor={named}{LightCyan}} + +at the start of the chapter and:: + + .. raw:: latex + + \endgroup + +at its end. + .. note:: - - Most options described next could also have been positioned as - :file:`sphinx.sty` package options. But for those where the key value - contains some LaTeX code the use of ``\sphinxsetup`` is mandatory. Hence - the whole ``'sphinxsetup'`` string is passed as argument to - ``\sphinxsetup``. + The colors above are made available via the ``svgnames`` option of + the "xcolor" package:: - - As an alternative to the ``'sphinxsetup'`` key, it is possible - to insert the ``\\sphinxsetup{key=value,..}`` inside the - ``'preamble'`` key. It is even possible to use the ``\sphinxsetup`` in - the body of the document, via the :rst:dir:`raw` directive, to modify - dynamically the option values: this is actually what we did for the - duration of this chapter for the PDF output, which is styled using:: - - \sphinxsetup{% - verbatimwithframe=false, - VerbatimColor={named}{OldLace}, - TitleColor={named}{DarkGoldenrod}, - hintBorderColor={named}{LightCoral}, - attentionborder=3pt, - attentionBorderColor={named}{Crimson}, - attentionBgColor={named}{FloralWhite}, - noteborder=2pt, - noteBorderColor={named}{Olive}, - cautionborder=3pt, - cautionBorderColor={named}{Cyan}, - cautionBgColor={named}{LightCyan}} - - and with the ``svgnames`` option having been passed to "xcolor" package:: - - latex_elements = { - 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', - } + latex_elements = { + 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', + } -Here are the currently available options together with their default values. - -.. caution:: - - These options correspond to what has been so far the default LaTeX - rendering by Sphinx; if in future Sphinx offers various *themes* for LaTeX, - the interface may change. - -.. attention:: - - LaTeX requires that keys with Boolean values use **lowercase** ``true`` or - ``false``. +The available styling options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. _latexsphinxsetuphmargin: -``hmargin`` - The dimensions of the horizontal margins. Legacy Sphinx default value is - ``1in`` (which stands for ``{1in,1in}``.) It is passed over as ``hmargin`` - option to ``geometry`` package. - - Here is an example for non-Japanese documents of use of this key:: +``hmargin, vmargin`` + The dimensions of the horizontal (resp. vertical) margins, passed as + ``hmargin`` (resp. ``vmargin``) option to + the ``geometry`` package. The default is ``1in``, which is equivalent to + ``{1in,1in}``. Example:: 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in', - Japanese documents currently accept only the form with only one dimension. - This option is handled then in a special manner in order for ``geometry`` - package to set the text width to an exact multiple of the *zenkaku* width - of the base document font. + Japanese documents currently accept only the one-dimension format for + these parameters. The ``geometry`` package is then passed suitable options + to get the text width set to an exact multiple of the *zenkaku* width, and + the text height set to an integer multiple of the baselineskip, with the + closest fit for the margins. .. hint:: - For a ``'manual'`` type document with :confval:`language` set to - ``'ja'``, which by default uses the ``jsbook`` LaTeX document class, the - dimension units, when the pointsize isn't ``10pt``, must be so-called TeX - "true" units:: + For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``, + use the ``nomag`` extra document class option (cf. + ``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called + TeX "true" units: 'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw', - This is due to the way the LaTeX class ``jsbook`` handles the - pointsize. - - Or, one uses regular units but with ``nomag`` as extra document class - option (cf. ``'extraclassoptions'`` key of :confval:`latex_elements`.) - - .. versionadded:: 1.5.3 - -``vmargin`` - The dimension of the vertical margins. Legacy Sphinx default value is - ``1in`` (or ``{1in,1in}``.) Passed over as ``vmargin`` option to - ``geometry``. - - Japanese documents will arrange for the text height to be an integer - multiple of the baselineskip, taking the closest match suitable for the - asked-for vertical margin. It can then be only one dimension. See notice - above. - .. versionadded:: 1.5.3 ``marginpar`` @@ -207,17 +183,12 @@ Here are the currently available options together with their default values. default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal includes are framed. Setting it to ``false`` does not deactivate use of package "framed", because it is still in use for the optional background - colour (see below). + colour. ``verbatimwrapslines`` default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's contents should wrap. - .. (comment) It is theoretically possible to customize this even - more and decide at which characters a line-break can occur and whether - before or after, but this is accessible currently only by re-defining - some macros with complicated LaTeX syntax from :file:`sphinx.sty`. - ``parsedliteralwraps`` default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's contents should wrap. @@ -237,29 +208,19 @@ Here are the currently available options together with their default values. ``verbatimvisiblespace`` default ``\textcolor{red}{\textvisiblespace}``. When a long code line is - split, space characters located at end of the line before the break are - displayed using this code. + split, the last space character from the source code line right before the + linebreak location is typeset using this. ``verbatimcontinued`` - The default is:: + A LaTeX macro inserted at start of continuation code lines. Its + (complicated...) default typesets a small red hook pointing to the right:: \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} - It is printed at start of continuation lines. This rather formidable - expression reserves twice the width of a typical character in the current - (monospaced) font and puts there a small red hook pointing to the right. - .. versionchanged:: 1.5 - The breaking of long code lines was introduced at 1.4.2. The space - reserved to the continuation symbol was changed at 1.5 to obey the - current font characteristics (this was needed as Sphinx 1.5 LaTeX - allows code-blocks in footnotes which use a smaller font size). - - .. hint:: - - This specification gives the same spacing as before 1.5:: - - \normalfont\normalsize\makebox[3ex][r]{\textcolor{red}{\tiny$\hookrightarrow$} + The breaking of long code lines was added at 1.4.2. The default + definition of the continuation symbol was changed at 1.5 to accomodate + various font sizes (e.g. code-blocks can be in footnotes). ``TitleColor`` default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured @@ -384,39 +345,31 @@ Here are the currently available options together with their default values. ``BeforeFootnote`` default ``\leavevmode\unskip``. LaTeX macros inserted before the footnote - mark. The default removes possible space before it. - - It can be set to empty (``BeforeFootnote={},``) to recover the earlier - behaviour of Sphinx, or alternatively contain a ``\nobreak\space`` or a - ``\thinspace`` after the ``\unskip`` to insert some chosen - (non-breakable) space. + mark. The default removes possible space before it (else, TeX could insert + a linebreak there). .. versionadded:: 1.5 - formerly, footnotes from explicit mark-up (but not automatically - generated ones) were preceded by a space in the output ``.tex`` file - hence a linebreak in PDF was possible. To avoid insertion of this space - one could use ``foo\ [#f1]`` mark-up, but this impacts all builders. ``HeaderFamily`` default ``\sffamily\bfseries``. Sets the font used by headings. -As seen above, key values may even be used for LaTeX commands. But don't -forget to double the backslashes if not using "raw" Python strings. +LaTeX macros and environments +----------------------------- -The LaTeX environments defined by Sphinx ----------------------------------------- +Here are some macros from the package file :file:`sphinx.sty` and class files +:file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names +thus allowing redefinitions. Check the respective files for the defaults. -Let us now list some macros from the package file -:file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or -:file:`sphinxmanual.cls`, which can be entirely redefined, if desired. +Macros +~~~~~~ -- text styling commands (they have one argument): ``\sphinx`` with - ```` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``, - ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``, - ``optional``. The non-prefixed macros will still be defined if option +- text styling commands ``\sphinx`` with ```` being one of + ``strong``, ``bfcode``, ``email``, ``tablecontinued``, ``titleref``, + ``menuselection``, ``accelerator``, ``crossref``, ``termref``, ``optional``. + The non-prefixed macros will still be defined if option :confval:`latex_keep_old_macro_names` has been set to ``True`` (default is - ``False``), in which case the prefixed macros expand to the - non-prefixed ones. + ``False``), in which case the prefixed macros expand to the non-prefixed + ones. .. versionadded:: 1.4.5 Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict @@ -427,21 +380,39 @@ Let us now list some macros from the package file already exists at ``sphinx.sty`` loading time, only the ``\sphinx`` prefixed one will be defined. The setting will be removed at 1.7. -- more text styling commands: ``\sphinxstyle`` with ```` one of +- more text styling: ``\sphinxstyle`` with ```` one of ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``, ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``, - ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``, - ``abbreviation``, ``literalintitle``. + ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``, + ``literalstrong``, ``abbreviation``, ``literalintitle``. .. versionadded:: 1.5 - the new macros are wrappers of the formerly hard-coded ``\texttt``, - ``\emph``, ... The default definitions can be found in - :file:`sphinx.sty`. + these macros were formerly hard-coded as non customizable ``\texttt``, + ``\emph``, etc... .. versionadded:: 1.6 ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows multiple paragraphs in header cells of tables. .. deprecated:: 1.6 macro ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7. +- by default the Sphinx style file ``sphinx.sty`` executes the command + ``\fvset{fontsize=\small}`` as part of its configuration of + ``fancyvrb.sty``. This may be overriden for example via + ``\fvset{fontsize=auto}`` which will let code listings use the ambient font + size. Refer to ``fancyvrb.sty``'s documentation for further keys. + + .. versionadded:: 1.5 +- the table of contents is typeset via ``\sphinxtableofcontents`` which is a + wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in + :file:`sphinxmanual.cls`) of standard ``\tableofcontents``. + + .. versionchanged:: 1.5 + formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. +- the ``\maketitle`` command is redefined by the class files + :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. + +Environments +~~~~~~~~~~~~ + - a :dudir:`figure` may have an optional legend with arbitrary body elements: they are rendered in a ``sphinxlegend`` environment. The default definition issues ``\small``, and ends with ``\par``. @@ -459,15 +430,17 @@ Let us now list some macros from the package file specific to each type, which can be set via ``'sphinxsetup'`` string. .. versionchanged:: 1.5 - use of public environment names, separate customizability of the parameters. + use of public environment names, separate customizability of the + parameters, such as ``noteBorderColor``, ``noteborder``, + ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ... - the :dudir:`contents` directive (with ``:local:`` option) and the :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. - See above for the three dimensions associated with it. + .. versionadded:: 1.4.2 + former code refactored into an environment allowing page breaks. .. versionchanged:: 1.5 - use of public names for the three lengths. The environment itself was - redefined to allow page breaks at release 1.4.2. -- the literal blocks (:rst:dir:`code-block` directives, etc ...), are + options ``shadowsep``, ``shadowsize``, ``shadowrule``. +- the literal blocks (via ``::`` or :rst:dir:`code-block`), are implemented using ``sphinxVerbatim`` environment which is a wrapper of ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling of the top caption and the wrapping of long lines, and a frame which allows @@ -476,41 +449,12 @@ Let us now list some macros from the package file allows a caption). .. versionchanged:: 1.5 - ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning - which is the one of ``OriginalVerbatim`` too), and custom one is called - ``sphinxVerbatim``. Also, earlier version of Sphinx used - ``OriginalVerbatim`` inside tables (captions were lost, long code lines - were not wrapped), it now uses there ``sphinxVerbatimintable``. + ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also + under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used + inside tables. .. versionadded:: 1.5 - the two customizable lengths, the ``sphinxVerbatimintable``, the boolean - toggles described above. -- by default the Sphinx style file ``sphinx.sty`` includes the command - ``\fvset{fontsize=\small}`` as part of its configuration of - ``fancyvrb.sty``. The user may override this for example via - ``\fvset{fontsize=auto}`` which will use for listings the ambient - font size. Refer to ``fancyvrb.sty``'s documentation for further keys. - - .. versionadded:: 1.5 - formerly, the use of ``\small`` for code listings was not customizable. -- the section, subsection, ... headings are set using *titlesec*'s - ``\titleformat`` command. Check :file:`sphinx.sty` for the definitions. -- for the ``'sphinxmanual'`` class (corresponding to the fifth element of - :confval:`latex_documents` being set to ``'manual'``), the chapter headings - can be customized using *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, - ``\ChTitleVar``. Check :file:`sphinx.sty` for the default definitions. They - are applied only if *fncychap* is loaded with option ``Bjarne``. It is also - possible to use an empty ``'fncychap'`` key, and use the *titlesec* - ``\titleformat`` command to style the chapter titles. - - .. versionchanged:: 1.5 - formerly, use of *fncychap* with other styles than ``Bjarne`` was - dysfunctional. -- the table of contents is typeset via ``\sphinxtableofcontents`` which is a - wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in - :file:`sphinxmanual.cls`) of standard ``\tableofcontents``. - - .. versionchanged:: 1.5 - formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + options ``verbatimwithframe``, ``verbatimwrapslines``, + ``verbatimsep``, ``verbatimborder``. - the bibliography and Python Module index are typeset respectively within environments ``sphinxthebibliography`` and ``sphinxtheindex``, which are simple wrappers of the non-modified ``thebibliography`` and ``theindex`` @@ -519,7 +463,20 @@ Let us now list some macros from the package file .. versionchanged:: 1.5 formerly, the original environments were modified by Sphinx. -- the list is not exhaustive: refer to :file:`sphinx.sty` for more. +Miscellany +~~~~~~~~~~ + +- the section, subsection, ... headings are set using *titlesec*'s + ``\titleformat`` command. +- for the ``'manual'`` docclass, the chapter headings can be customized using + *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File + :file:`sphinx.sty` has custom re-definitions in case of *fncychap* + option ``Bjarne``. + + .. versionchanged:: 1.5 + formerly, use of *fncychap* with other styles than ``Bjarne`` was + dysfunctional. +- check file :file:`sphinx.sty` for more... .. hint::