From b35198d8475fe89aaf9a5224a9832fb394e73cca Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 14 Apr 2018 23:15:31 +0900 Subject: [PATCH 01/25] Deprecate highlightlang directive highlightlang directive is not documented, and marked as old in v0.2. --- CHANGES | 1 + doc/config.rst | 2 +- doc/extdev/index.rst | 5 +++++ doc/latex.rst | 2 +- doc/markdown.rst | 2 +- doc/theming.rst | 2 +- doc/usage/restructuredtext/basics.rst | 2 +- doc/usage/restructuredtext/field-lists.rst | 2 +- sphinx/directives/code.py | 15 ++++++++++++++- 9 files changed, 26 insertions(+), 7 deletions(-) diff --git a/CHANGES b/CHANGES index d07d4f132..f7d9b908b 100644 --- a/CHANGES +++ b/CHANGES @@ -36,6 +36,7 @@ Deprecated * ``env._nitpick_ignore`` is deprecated * ``app.override_domain()`` is deprecated * ``app.add_stylesheet()`` is deprecated +* ``highlightlang`` directive is deprecated For more details, see `deprecation APIs list `_ diff --git a/doc/config.rst b/doc/config.rst index 46958cde6..fe8c87419 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -1,4 +1,4 @@ -.. highlightlang:: python +.. highlight:: python .. _build-config: diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 94a23aaea..aa8a50f5a 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -114,6 +114,11 @@ The following is a list of deprecated interface. - (will be) Removed - Alternatives + * - :rst:dir:`highlightlang` + - 1.8 + - 4.0 + - :rst:dir:`highlight` + * - :meth:`~sphinx.application.Sphinx.add_stylesheet()` - 1.8 - 4.0 diff --git a/doc/latex.rst b/doc/latex.rst index b50f49377..5592aecfa 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1,4 +1,4 @@ -.. highlightlang:: python +.. highlight:: python .. _latex: diff --git a/doc/markdown.rst b/doc/markdown.rst index e94a821da..1c8c4de53 100644 --- a/doc/markdown.rst +++ b/doc/markdown.rst @@ -1,4 +1,4 @@ -.. highlightlang:: python +.. highlight:: python .. _markdown: diff --git a/doc/theming.rst b/doc/theming.rst index 67dd6adc2..b2b65da5c 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -1,4 +1,4 @@ -.. highlightlang:: python +.. highlight:: python HTML theming support ==================== diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 9aa8e1ef7..b9fdf64bd 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -1,4 +1,4 @@ -.. highlightlang:: rst +.. highlight:: rst .. _rst-primer: diff --git a/doc/usage/restructuredtext/field-lists.rst b/doc/usage/restructuredtext/field-lists.rst index 10ded3ea4..fcecfe708 100644 --- a/doc/usage/restructuredtext/field-lists.rst +++ b/doc/usage/restructuredtext/field-lists.rst @@ -1,4 +1,4 @@ -.. highlightlang:: rst +.. highlight:: rst =========== Field Lists diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 1c294ec7b..713e5ad0c 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -9,6 +9,7 @@ import codecs import sys +import warnings from difflib import unified_diff from docutils import nodes @@ -17,6 +18,7 @@ from docutils.statemachine import ViewList from six import text_type from sphinx import addnodes +from sphinx.deprecation import RemovedInSphinx40Warning from sphinx.locale import __ from sphinx.util import logging from sphinx.util import parselinenos @@ -59,6 +61,17 @@ class Highlight(SphinxDirective): linenothreshold=linenothreshold)] +class HighlightLang(Highlight): + """highlightlang directive (deprecated)""" + + def run(self): + # type: () -> List[nodes.Node] + warnings.warn('highlightlang directive is deprecated. ' + 'Please use highlight directive instead.', + RemovedInSphinx40Warning) + return Highlight.run(self) + + def dedent_lines(lines, dedent, location=None): # type: (List[unicode], int, Any) -> List[unicode] if not dedent: @@ -462,7 +475,7 @@ class LiteralInclude(SphinxDirective): def setup(app): # type: (Sphinx) -> Dict[unicode, Any] directives.register_directive('highlight', Highlight) - directives.register_directive('highlightlang', Highlight) # old + directives.register_directive('highlightlang', HighlightLang) directives.register_directive('code-block', CodeBlock) directives.register_directive('sourcecode', CodeBlock) directives.register_directive('literalinclude', LiteralInclude) From b689fb1c12252984a3fa0ed90e7b0276919cf22b Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Fri, 20 Apr 2018 02:10:30 -0400 Subject: [PATCH 02/25] Wrap graphviz diagrams in
The graphviz extension is modified to wrap the `` and `` tags it creates for diagrams in the png and svg formats in an additional `
...
` tag. This allows to apply additional CSS styling to the the diagrams that cannot be applied to `` and `` directly. Most notably, div.graphviz { overflow: auto; } would be a useful style that the standard themes might consider. In any case, it would allow users to add custom CSS code to their project that gets around the problems with inheritance-diagrams discussed in https://github.com/sphinx-doc/sphinx/issues/4865 The tests for the `grahviz` and `inheritance_diagram` have been modified to test for the presence of the additional `
` tag. Closes #4865 --- sphinx/ext/graphviz.py | 12 ++++++++---- tests/test_ext_graphviz.py | 28 ++++++++++++++------------- tests/test_ext_inheritance_diagram.py | 6 ++++-- 3 files changed, 27 insertions(+), 19 deletions(-) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index bc348f4e1..f0b321378 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -290,21 +290,25 @@ def render_dot_html(self, node, code, options, prefix='graphviz', self.body.append('
' % (node['align'], node['align'])) if format == 'svg': - svgtag = ''' -

%s

\n''' % (fname, alt) + svgtag = '''
+

%s

\n''' % (fname, alt) self.body.append(svgtag) else: with codecs.open(outfn + '.map', 'r', encoding='utf-8') as mapfile: # type: ignore imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code) if imgmap.clickable: # has a map - self.body.append('%s\n' % + self.body.append('
') + self.body.append('%s' % (fname, alt, imgmap.id, imgcss)) + self.body.append('
\n') self.body.append(imgmap.generate_clickable_map()) else: # nothing in image map - self.body.append('%s\n' % + self.body.append('
') + self.body.append('%s' % (fname, alt, imgcss)) + self.body.append('
\n') if 'align' in node: self.body.append('
\n') diff --git a/tests/test_ext_graphviz.py b/tests/test_ext_graphviz.py index 3efab6b56..df096ce62 100644 --- a/tests/test_ext_graphviz.py +++ b/tests/test_ext_graphviz.py @@ -22,24 +22,26 @@ def test_graphviz_png_html(app, status, warning): app.builder.build_all() content = (app.outdir / 'index.html').text() - html = (r'
\s*\s*

' + html = (r'

\s*' + r'
\s*

' r'caption of graph.*

\s*
') assert re.search(html, content, re.S) - html = 'Hello \n graphviz world' + html = 'Hello
\n graphviz world' assert re.search(html, content, re.S) html = 'digraph {\n bar -> baz\n}' assert re.search(html, content, re.M) - html = (r'
\s*\s*

' + html = (r'

\s*' + r'
\s*

' r'on right.*

\s*
') assert re.search(html, content, re.S) html = (r'
' - r'\"digraph\"digraph\n
') + r'}\" />
\n
') assert re.search(html, content, re.S) @@ -52,34 +54,34 @@ def test_graphviz_svg_html(app, status, warning): content = (app.outdir / 'index.html').text() html = (r'
\n' - r'\n' + r'
\n' r'\s+

digraph foo {\n' r'bar -> baz\n' - r'}

\n' + r'}

\n' r'

' r'caption of graph.*

\n
') assert re.search(html, content, re.S) - html = (r'Hello \n' - r'\s+

graph

\n' + html = (r'Hello
\n' + r'\s+

graph

\n' r' graphviz world') assert re.search(html, content, re.S) html = (r'
\n' - r'\n' + r'
\n' r'\s+

digraph bar {\n' r'foo -> bar\n' - r'}

\n' + r'}

\n' r'

' r'on right.*

\n' r'') assert re.search(html, content, re.S) html = (r'
' - r'\n' + r'
\n' r'\s+

digraph foo {\n' r'centered\n' - r'}

\n' + r'}

\n' r'') assert re.search(html, content, re.S) diff --git a/tests/test_ext_inheritance_diagram.py b/tests/test_ext_inheritance_diagram.py index ad106e6c6..dfee015e0 100644 --- a/tests/test_ext_inheritance_diagram.py +++ b/tests/test_ext_inheritance_diagram.py @@ -25,8 +25,9 @@ def test_inheritance_diagram_html(app, status, warning): content = (app.outdir / 'index.html').text() pattern = ('
\n' + '
' 'Inheritance diagram of test.Foo\n

' + 'class="inheritance"/>

\n

' 'Test Foo!\xb6

') assert re.search(pattern, content, re.M) @@ -62,8 +63,9 @@ def test_inheritance_diagram_latex_alias(app, status, warning): content = (app.outdir / 'index.html').text() pattern = ('
\n' + '
' 'Inheritance diagram of test.Foo\n

' + 'class="inheritance"/>

\n

' 'Test Foo!\xb6

') assert re.search(pattern, content, re.M) From 4a2b22737660ad1a933a7da5149725b3918e8c57 Mon Sep 17 00:00:00 2001 From: Michael Goerz Date: Sat, 21 Apr 2018 00:59:27 -0400 Subject: [PATCH 03/25] Allow imgcls as class for SVG Graphviz For consistency, the `` tag for the SVG output of a inheritance-diagram should have the same `class="inheritance"` attribute that the corresponding `` tag for the PNG format has. This allows to define the CSS attribute object.inheritance { max-width: 100%; } which for SVG (unlike PNG) actually works and makes sense. Added a test for inheritance-diagrams in SVG. --- sphinx/ext/graphviz.py | 8 +++++--- tests/test_ext_graphviz.py | 8 ++++---- tests/test_ext_inheritance_diagram.py | 21 ++++++++++++++++++++- 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index f0b321378..127146f94 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -290,9 +290,11 @@ def render_dot_html(self, node, code, options, prefix='graphviz', self.body.append('
' % (node['align'], node['align'])) if format == 'svg': - svgtag = '''
-

%s

\n''' % (fname, alt) - self.body.append(svgtag) + self.body.append('
') + self.body.append('\n' % + (fname, imgcss)) + self.body.append('

%s

' % alt) + self.body.append('
\n') else: with codecs.open(outfn + '.map', 'r', encoding='utf-8') as mapfile: # type: ignore imgmap = ClickableMapDefinition(outfn + '.map', mapfile.read(), dot=code) diff --git a/tests/test_ext_graphviz.py b/tests/test_ext_graphviz.py index df096ce62..9b53876db 100644 --- a/tests/test_ext_graphviz.py +++ b/tests/test_ext_graphviz.py @@ -55,7 +55,7 @@ def test_graphviz_svg_html(app, status, warning): html = (r'
\n' r'
\n' - r'\s+

digraph foo {\n' + r'\s*

digraph foo {\n' r'bar -> baz\n' r'}

\n' r'

' @@ -63,13 +63,13 @@ def test_graphviz_svg_html(app, status, warning): assert re.search(html, content, re.S) html = (r'Hello

\n' - r'\s+

graph

\n' + r'\s*

graph

\n' r' graphviz world') assert re.search(html, content, re.S) html = (r'
\n' r'
\n' - r'\s+

digraph bar {\n' + r'\s*

digraph bar {\n' r'foo -> bar\n' r'}

\n' r'

' @@ -79,7 +79,7 @@ def test_graphviz_svg_html(app, status, warning): html = (r'

' r'
\n' - r'\s+

digraph foo {\n' + r'\s*

digraph foo {\n' r'centered\n' r'}

\n' r'
') diff --git a/tests/test_ext_inheritance_diagram.py b/tests/test_ext_inheritance_diagram.py index dfee015e0..8456cda4a 100644 --- a/tests/test_ext_inheritance_diagram.py +++ b/tests/test_ext_inheritance_diagram.py @@ -19,7 +19,7 @@ from sphinx.ext.inheritance_diagram import InheritanceException, import_classes @pytest.mark.sphinx('html', testroot='ext-inheritance_diagram') @pytest.mark.usefixtures('if_graphviz_found') -def test_inheritance_diagram_html(app, status, warning): +def test_inheritance_diagram_png_html(app, status, warning): app.builder.build_all() content = (app.outdir / 'index.html').text() @@ -33,6 +33,25 @@ def test_inheritance_diagram_html(app, status, warning): assert re.search(pattern, content, re.M) +@pytest.mark.sphinx('html', testroot='ext-inheritance_diagram', + confoverrides={'graphviz_output_format': 'svg'}) +@pytest.mark.usefixtures('if_graphviz_found') +def test_inheritance_diagram_svg_html(app, status, warning): + app.builder.build_all() + + content = (app.outdir / 'index.html').text() + + pattern = ('
\n' + '
' + '\n' + '

Inheritance diagram of test.Foo

' + '
\n

' + 'Test Foo!\xb6

') + assert re.search(pattern, content, re.M) + + @pytest.mark.sphinx('latex', testroot='ext-inheritance_diagram') @pytest.mark.usefixtures('if_graphviz_found') def test_inheritance_diagram_latex(app, status, warning): From 81946e423a54c88edc0b6fd3d0a9606a5ba08c61 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 29 Mar 2018 22:45:20 +0900 Subject: [PATCH 04/25] Let docutils know the location of ``docutils.conf`` for Sphinx --- CHANGES | 2 ++ sphinx/cmd/build.py | 3 +- sphinx/environment/__init__.py | 6 ++-- sphinx/setup_command.py | 3 +- sphinx/util/docutils.py | 51 +++++++++++++++++++++++++--------- tests/test_docutilsconf.py | 24 +++++++++++----- 6 files changed, 63 insertions(+), 26 deletions(-) diff --git a/CHANGES b/CHANGES index 5bea0d78b..5ac921cf9 100644 --- a/CHANGES +++ b/CHANGES @@ -23,6 +23,8 @@ Incompatible changes :py:meth:`.Sphinx.add_transform()` * #4827: All ``substitution_definition`` nodes are removed from doctree on reading phase +* ``docutils.conf`` on ``$HOME`` and ``/etc`` directories are ignored. Only + ``docutils.conf`` on confdir is refered. Deprecated ---------- diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py index bc8e5aa9c..53e93fb99 100644 --- a/sphinx/cmd/build.py +++ b/sphinx/cmd/build.py @@ -293,7 +293,8 @@ def build_main(argv=sys.argv[1:]): # type: ignore app = None try: - with patch_docutils(), docutils_namespace(): + confdir = args.confdir or args.sourcedir + with patch_docutils(confdir), docutils_namespace(): app = Sphinx(args.sourcedir, args.confdir, args.outputdir, args.doctreedir, args.builder, confoverrides, status, warning, args.freshenv, args.warningiserror, diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index ccdeb03bd..f69a44d76 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -19,7 +19,6 @@ from collections import defaultdict from copy import copy from os import path -from docutils.frontend import OptionParser from docutils.utils import Reporter, get_source_line from six import BytesIO, class_types, next from six.moves import cPickle as pickle @@ -561,9 +560,8 @@ class BuildEnvironment(object): """Parse a file and add/update inventory entries for the doctree.""" self.prepare_settings(docname) - docutilsconf = path.join(self.srcdir, 'docutils.conf') - # read docutils.conf from source dir, not from current dir - OptionParser.standard_config_files[1] = docutilsconf + # Add confdir/docutils.conf to dependencies list if exists + docutilsconf = path.join(self.app.confdir, 'docutils.conf') if path.isfile(docutilsconf): self.note_dependency(docutilsconf) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index 37fc2d042..eebc70def 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -179,7 +179,8 @@ class BuildDoc(Command): app = None try: - with patch_docutils(), docutils_namespace(): + confdir = self.config_dir or self.source_dir + with patch_docutils(confdir), docutils_namespace(): app = Sphinx(self.source_dir, self.config_dir, builder_target_dir, self.doctree_dir, builder, confoverrides, status_stream, diff --git a/sphinx/util/docutils.py b/sphinx/util/docutils.py index 747b24565..b09d4e841 100644 --- a/sphinx/util/docutils.py +++ b/sphinx/util/docutils.py @@ -10,16 +10,17 @@ """ from __future__ import absolute_import +import os import re import types import warnings from contextlib import contextmanager from copy import copy from distutils.version import LooseVersion +from os import path import docutils from docutils import nodes -from docutils.languages import get_language from docutils.parsers.rst import Directive, directives, roles, convert_directive_function from docutils.statemachine import StateMachine from docutils.utils import Reporter @@ -34,7 +35,7 @@ report_re = re.compile('^(.+?:(?:\\d+)?): \\((DEBUG|INFO|WARNING|ERROR|SEVERE)/( if False: # For type annotation - from typing import Any, Callable, Generator, Iterator, List, Set, Tuple # NOQA + from typing import Any, Callable, Generator, List, Set, Tuple # NOQA from docutils.statemachine import State, ViewList # NOQA from sphinx.config import Config # NOQA from sphinx.environment import BuildEnvironment # NOQA @@ -47,7 +48,7 @@ additional_nodes = set() # type: Set[nodes.Node] @contextmanager def docutils_namespace(): - # type: () -> Iterator[None] + # type: () -> Generator[None, None, None] """Create namespace for reST parsers.""" try: _directives = copy(directives._directives) @@ -94,29 +95,53 @@ def unregister_node(node): delattr(nodes.SparseNodeVisitor, 'depart_' + node.__name__) -def patched_get_language(language_code, reporter=None): - # type: (unicode, Reporter) -> Any - """A wrapper for docutils.languages.get_language(). +@contextmanager +def patched_get_language(): + # type: () -> Generator[None, None, None] + """Patch docutils.languages.get_language() temporarily. This ignores the second argument ``reporter`` to suppress warnings. refs: https://github.com/sphinx-doc/sphinx/issues/3788 """ - return get_language(language_code) + from docutils.languages import get_language + def patched_get_language(language_code, reporter=None): + # type: (unicode, Reporter) -> Any + return get_language(language_code) -@contextmanager -def patch_docutils(): - # type: () -> Iterator[None] - """Patch to docutils temporarily.""" try: docutils.languages.get_language = patched_get_language - yield finally: # restore original implementations docutils.languages.get_language = get_language +@contextmanager +def using_user_docutils_conf(confdir): + # type: (unicode) -> Generator[None, None, None] + """Let docutils know the location of ``docutils.conf`` for Sphinx.""" + try: + docutilsconfig = os.environ.get('DOCUTILSCONFIG', None) + if confdir: + os.environ['DOCUTILSCONFIG'] = path.join(path.abspath(confdir), 'docutils.conf') # type: ignore # NOQA + + yield + finally: + if docutilsconfig is None: + os.environ.pop('DOCUTILSCONFIG') + else: + os.environ['DOCUTILSCONFIG'] = docutilsconfig + + +@contextmanager +def patch_docutils(confdir=None): + # type: (unicode) -> Generator[None, None, None] + """Patch to docutils temporarily.""" + with patched_get_language(), using_user_docutils_conf(confdir): + yield + + class ElementLookupError(Exception): pass @@ -257,7 +282,7 @@ def directive_helper(obj, has_content=None, argument_spec=None, **option_spec): @contextmanager def switch_source_input(state, content): - # type: (State, ViewList) -> Generator + # type: (State, ViewList) -> Generator[None, None, None] """Switch current source input of state temporarily.""" try: # remember the original ``get_source_and_line()`` method diff --git a/tests/test_docutilsconf.py b/tests/test_docutilsconf.py index 2332dcf50..989edc6a8 100644 --- a/tests/test_docutilsconf.py +++ b/tests/test_docutilsconf.py @@ -15,6 +15,7 @@ import sys import pytest from sphinx.testing.path import path +from sphinx.util.docutils import patch_docutils def regex_count(expr, result): @@ -23,7 +24,9 @@ def regex_count(expr, result): @pytest.mark.sphinx('html', testroot='docutilsconf', freshenv=True, docutilsconf='') def test_html_with_default_docutilsconf(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) + result = (app.outdir / 'contents.html').text(encoding='utf-8') assert regex_count(r'', result) == 1 @@ -39,7 +42,9 @@ def test_html_with_default_docutilsconf(app, status, warning): '\n') ) def test_html_with_docutilsconf(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) + result = (app.outdir / 'contents.html').text(encoding='utf-8') assert regex_count(r'', result) == 0 @@ -50,25 +55,29 @@ def test_html_with_docutilsconf(app, status, warning): @pytest.mark.sphinx('html', testroot='docutilsconf') def test_html(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) assert warning.getvalue() == '' @pytest.mark.sphinx('latex', testroot='docutilsconf') def test_latex(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) assert warning.getvalue() == '' @pytest.mark.sphinx('man', testroot='docutilsconf') def test_man(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) assert warning.getvalue() == '' @pytest.mark.sphinx('texinfo', testroot='docutilsconf') def test_texinfo(app, status, warning): - app.builder.build(['contents']) + with patch_docutils(app.confdir): + app.builder.build(['contents']) @pytest.mark.sphinx('html', testroot='docutilsconf', @@ -87,4 +96,5 @@ def test_docutils_source_link_with_nonascii_file(app, status, warning): 'nonascii filename not supported on this filesystem encoding: ' '%s', FILESYSTEMENCODING) - app.builder.build_all() + with patch_docutils(app.confdir): + app.builder.build_all() From 622119a9d4e1294ce9718e490983edf58b50e6ac Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 28 Apr 2018 11:39:13 +0900 Subject: [PATCH 05/25] Fix #789: ``:samp:`` role supports to escape curly braces with backslash --- CHANGES | 1 + doc/usage/restructuredtext/roles.rst | 3 ++ sphinx/roles.py | 47 ++++++++++++---- tests/test_roles.py | 81 ++++++++++++++++++++++++++++ 4 files changed, 122 insertions(+), 10 deletions(-) create mode 100644 tests/test_roles.py diff --git a/CHANGES b/CHANGES index 12787e277..a53d72f2d 100644 --- a/CHANGES +++ b/CHANGES @@ -23,6 +23,7 @@ Incompatible changes :py:meth:`.Sphinx.add_transform()` * #4827: All ``substitution_definition`` nodes are removed from doctree on reading phase +* #789: ``:samp:`` role supports to escape curly braces with backslash Deprecated ---------- diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index 7e68b3e2a..04991c3a9 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -406,6 +406,9 @@ different style: If you don't need the "variable part" indication, use the standard ````code```` instead. + .. versionchanged:: 1.8 + Allowed to escape curly braces with backslash + There is also an :rst:role:`index` role to generate index entries. The following roles generate external links: diff --git a/sphinx/roles.py b/sphinx/roles.py index 2971c8fc3..453eb5aa0 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -284,6 +284,7 @@ def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): _litvar_re = re.compile('{([^}]+)}') +parens_re = re.compile(r'(\\*{|\\*})') def emph_literal_role(typ, rawtext, text, lineno, inliner, @@ -296,17 +297,43 @@ def emph_literal_role(typ, rawtext, text, lineno, inliner, else: typ = typ.lower() - text = utils.unescape(text) - pos = 0 retnode = nodes.literal(role=typ.lower(), classes=[typ]) - for m in _litvar_re.finditer(text): # type: ignore - if m.start() > pos: - txt = text[pos:m.start()] - retnode += nodes.Text(txt, txt) - retnode += nodes.emphasis(m.group(1), m.group(1)) - pos = m.end() - if pos < len(text): - retnode += nodes.Text(text[pos:], text[pos:]) + parts = list(parens_re.split(utils.unescape(text))) + stack = [''] + for part in parts: + matched = parens_re.match(part) + if matched: + backslashes = len(part) - 1 + if backslashes % 2 == 1: # escaped + stack[-1] += "\\" * int((backslashes - 1) / 2) + part[-1] + elif part[-1] == '{': # rparen + stack[-1] += "\\" * int(backslashes / 2) + if len(stack) >= 2 and stack[-2] == "{": + # nested + stack[-1] += "{" + else: + # start emphasis + stack.append('{') + stack.append('') + else: # lparen + stack[-1] += "\\" * int(backslashes / 2) + if len(stack) == 3 and stack[1] == "{" and len(stack[2]) > 0: + # emphasized word found + if stack[0]: + retnode += nodes.Text(stack[0], stack[0]) + retnode += nodes.emphasis(stack[2], stack[2]) + stack = [''] + else: + # emphasized word not found; the rparen is not a special symbol + stack.append('}') + stack = [''.join(stack)] + else: + stack[-1] += part + if ''.join(stack): + # remaining is treated as Text + text = ''.join(stack) + retnode += nodes.Text(text, text) + return [retnode], [] diff --git a/tests/test_roles.py b/tests/test_roles.py new file mode 100644 index 000000000..13b4e194d --- /dev/null +++ b/tests/test_roles.py @@ -0,0 +1,81 @@ +# -*- coding: utf-8 -*- +""" + test_roles + ~~~~~~~~~~ + + Test sphinx.roles + + :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from docutils import nodes +from mock import Mock + +from sphinx.roles import emph_literal_role +from sphinx.testing.util import assert_node + + +def test_samp(): + # normal case + text = 'print 1+{variable}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, ("print 1+", + [nodes.emphasis, "variable"])],)) + assert msg == [] + + # two emphasis items + text = 'print {1}+{variable}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, ("print ", + [nodes.emphasis, "1"], + "+", + [nodes.emphasis, "variable"])],)) + assert msg == [] + + # empty curly brace + text = 'print 1+{}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, "print 1+{}"],)) + assert msg == [] + + # half-opened variable + text = 'print 1+{variable' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, "print 1+{variable"],)) + assert msg == [] + + # nested + text = 'print 1+{{variable}}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, ("print 1+", + [nodes.emphasis, "{variable"], + "}")],)) + assert msg == [] + + # emphasized item only + text = '{variable}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, nodes.emphasis, "variable"],)) + assert msg == [] + + # escaping + text = r'print 1+\{variable}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, "print 1+{variable}"],)) + assert msg == [] + + # escaping (2) + text = r'print 1+\{{variable}\}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, ("print 1+{", + [nodes.emphasis, "variable"], + "}")],)) + assert msg == [] + + # escape a backslash + text = r'print 1+\\{variable}' + ret, msg = emph_literal_role('samp', text, text, 0, Mock()) + assert_node(ret, ([nodes.literal, ("print 1+\\", + [nodes.emphasis, "variable"])],)) + assert msg == [] From feee462836677b23041a910734be221bcc0731bb Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 29 Apr 2018 22:23:37 +0900 Subject: [PATCH 06/25] Update CHANGES for PR #4866 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index b3f416c7e..8b11561ba 100644 --- a/CHANGES +++ b/CHANGES @@ -82,6 +82,7 @@ Features added :rst:role:`menuselection` (refs: #4830) * Add ``Config.read()`` classmethod to create a new config object from configuration file +* #4866: Wrap graphviz diagrams in ``
`` tag Bugs fixed ---------- From 7a8d1dc08c94c96e29da235b065a2eba6b056cc5 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 29 Mar 2018 15:08:34 +0100 Subject: [PATCH 07/25] doc: Fix line length Keep things in the fixed docs under 80 characters. Signed-off-by: Stephen Finucane --- doc/usage/quickstart.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index 3c8941e10..adda610ab 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -236,7 +236,8 @@ so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line. If you use non-ASCII characters in any string value, you need to use Python Unicode strings (like ``project = u'Exposé'``). -|more| See :ref:`build-config` for documentation of all available config values. +|more| See :ref:`build-config` for documentation of all available config +values. .. todo:: Move this entire doc to a different section From dcf07f80052fd3011415d7ec7f49cea7228a3f1f Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 6 Feb 2018 11:22:47 +0000 Subject: [PATCH 08/25] doc: Rework "markdown" document There are a number of cleanup items. - Some paragraphs are reworded or clarified - Semantic markup is added where possible - Everything is wrapped to ~80 characters Signed-off-by: Stephen Finucane --- doc/config.rst | 2 +- doc/markdown.rst | 44 +++++++++++++++++++++----------------------- 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index ec3abf813..090a8eb80 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -136,7 +136,7 @@ General configuration .. note:: - Read more about how to use Markdown with Sphinx at :ref:`markdown`. + Read more about how to use Markdown with Sphinx at :doc:`/markdown`. .. versionadded:: 1.3 diff --git a/doc/markdown.rst b/doc/markdown.rst index 1c8c4de53..2855eb8f2 100644 --- a/doc/markdown.rst +++ b/doc/markdown.rst @@ -1,33 +1,26 @@ .. highlight:: python -.. _markdown: - -Markdown support -================ - -`Markdown `__ is a lightweight markup language with a simplistic plain -text formatting syntax. -It exists in many syntactically different *flavors*. -To support Markdown-based documentation, Sphinx can use -`recommonmark `__. -recommonmark is a Docutils bridge to `CommonMark-py `__, a -Python package for parsing the `CommonMark `__ Markdown flavor. +======== +Markdown +======== +`Markdown`_ is a lightweight markup language with a simplistic plain text +formatting syntax. It exists in many syntactically different *flavors*. To +support Markdown-based documentation, Sphinx can use `recommonmark`_. +recommonmark is a Docutils bridge to `CommonMark-py`_, a Python package for +parsing the `CommonMark`_ Markdown flavor. Configuration ------------- To configure your Sphinx project for Markdown support, proceed as follows: -#. Install recommonmark: - - :: +#. Install recommonmark:: pip install recommonmark -#. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file: - - :: +#. Add the Markdown parser to the ``source_parsers`` configuration variable in + your Sphinx configuration file:: source_parsers = { '.md': 'recommonmark.parser.CommonMarkParser', @@ -35,11 +28,16 @@ To configure your Sphinx project for Markdown support, proceed as follows: You can replace `.md` with a filename extension of your choice. -#. Add the Markdown filename extension to the ``source_suffix`` configuration variable: - - :: +#. Add the Markdown filename extension to the ``source_suffix`` configuration + variable:: source_suffix = ['.rst', '.md'] -#. You can further configure recommonmark to allow custom syntax that standard CommonMark doesn't support. Read more in - the `recommonmark documentation `__. +#. You can further configure recommonmark to allow custom syntax that standard + CommonMark doesn't support. Read more in the `recommonmark documentation + `__. + +.. _Markdown: https://daringfireball.net/projects/markdown/ +.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html +.. _CommonMark-py: +.. _CommonMark: http://commonmark.org/ From d1972ac5b54397ffa1ff30784bbcb9ac78b4c293 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:13:16 +0000 Subject: [PATCH 09/25] doc: Add "markdown" section to usage guide Signed-off-by: Stephen Finucane --- doc/config.rst | 3 ++- doc/contents.rst | 2 +- doc/{ => usage}/markdown.rst | 0 3 files changed, 3 insertions(+), 2 deletions(-) rename doc/{ => usage}/markdown.rst (100%) diff --git a/doc/config.rst b/doc/config.rst index 090a8eb80..ab8d48e12 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -136,7 +136,8 @@ General configuration .. note:: - Read more about how to use Markdown with Sphinx at :doc:`/markdown`. + Refer to :doc:`/usage/markdown` for more information on using Markdown + with Sphinx. .. versionadded:: 1.3 diff --git a/doc/contents.rst b/doc/contents.rst index 3af0aa58c..4a8a4d947 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -10,6 +10,7 @@ Sphinx documentation contents usage/installation usage/quickstart usage/restructuredtext/index + usage/markdown intro man/index @@ -20,7 +21,6 @@ Sphinx documentation contents setuptools templating latex - markdown extensions extdev/index websupport diff --git a/doc/markdown.rst b/doc/usage/markdown.rst similarity index 100% rename from doc/markdown.rst rename to doc/usage/markdown.rst From ac19be3585b6f1407d3ce0ac9f83d1b899ae8dfd Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sat, 31 Mar 2018 13:18:55 +0100 Subject: [PATCH 10/25] doc: Rework "config" document Wrap some lines and format some definition lists as such. Signed-off-by: Stephen Finucane --- doc/config.rst | 345 ++++++++++++++++++++++++++++--------------------- 1 file changed, 201 insertions(+), 144 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index ab8d48e12..27d84b293 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -2,8 +2,9 @@ .. _build-config: -The build configuration file -============================ +============= +Configuration +============= .. module:: conf :synopsis: Build configuration file. @@ -14,11 +15,10 @@ and contains (almost) all configuration needed to customize Sphinx input and output behavior. An optional file `docutils.conf`_ can be added to the configuration - directory to adjust `Docutils`_ configuration if not otherwise overriden or + directory to adjust `Docutils`_ configuration if not otherwise overridden or set by Sphinx. .. _`docutils`: http://docutils.sourceforge.net/ - .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html The configuration file is executed as Python code at build time (using @@ -36,8 +36,8 @@ Important points to note: ``"sphinx.builders.Builder"`` means the ``Builder`` class in the ``sphinx.builders`` module. -* Remember that document names use ``/`` as the path separator and don't contain - the file name extension. +* Remember that document names use ``/`` as the path separator and don't + contain the file name extension. * Since :file:`conf.py` is read as a Python file, the usual rules apply for encodings and Unicode support: declare the encoding using an encoding cookie @@ -82,8 +82,8 @@ General configuration That way, you can load an extension called ``extname`` from the subdirectory ``sphinxext``. - The configuration file itself can be an extension; for that, you only need to - provide a :func:`setup` function in it. + The configuration file itself can be an extension; for that, you only need + to provide a :func:`setup` function in it. .. confval:: source_suffix @@ -152,9 +152,10 @@ General configuration .. confval:: exclude_patterns - A list of glob-style patterns that should be excluded when looking for source - files. [1]_ They are matched against the source file names relative to the - source directory, using slashes as directory separators on all platforms. + A list of glob-style patterns that should be excluded when looking for + source files. [1]_ They are matched against the source file names relative + to the source directory, using slashes as directory separators on all + platforms. Example patterns: @@ -182,10 +183,10 @@ General configuration .. confval:: template_bridge - A string with the fully-qualified name of a callable (or simply a class) that - returns an instance of :class:`~sphinx.application.TemplateBridge`. This - instance is then used to render HTML documents, and possibly the output of - other builders (currently the changes builder). (Note that the template + A string with the fully-qualified name of a callable (or simply a class) + that returns an instance of :class:`~sphinx.application.TemplateBridge`. + This instance is then used to render HTML documents, and possibly the output + of other builders (currently the changes builder). (Note that the template bridge must be made theme-aware if HTML themes are to be used.) .. confval:: rst_epilog @@ -248,9 +249,9 @@ General configuration .. confval:: keep_warnings - If true, keep warnings as "system message" paragraphs in the built documents. - Regardless of this setting, warnings are always written to the standard error - stream when ``sphinx-build`` is run. + If true, keep warnings as "system message" paragraphs in the built + documents. Regardless of this setting, warnings are always written to the + standard error stream when ``sphinx-build`` is run. The default is ``False``, the pre-0.5 behavior was to always keep them. @@ -303,8 +304,8 @@ General configuration .. confval:: needs_sphinx If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will - compare it with its version and refuse to build if it is too old. Default is - no requirement. + compare it with its version and refuse to build if it is too old. Default + is no requirement. .. versionadded:: 1.0 @@ -313,8 +314,8 @@ General configuration .. confval:: needs_extensions - This value can be a dictionary specifying version requirements for extensions - in :confval:`extensions`, e.g. ``needs_extensions = + This value can be a dictionary specifying version requirements for + extensions in :confval:`extensions`, e.g. ``needs_extensions = {'sphinxcontrib.something': '1.5'}``. The version strings should be in the form ``major.minor``. Requirements do not have to be specified for all extensions, only for those you want to check. @@ -352,10 +353,10 @@ General configuration .. confval:: nitpick_ignore - A list of ``(type, target)`` tuples (by default empty) that should be ignored - when generating warnings in "nitpicky mode". Note that ``type`` should - include the domain name if present. Example entries would be ``('py:func', - 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. + A list of ``(type, target)`` tuples (by default empty) that should be + ignored when generating warnings in "nitpicky mode". Note that ``type`` + should include the domain name if present. Example entries would be + ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``. .. versionadded:: 1.1 @@ -367,8 +368,8 @@ General configuration .. note:: - The LaTeX builder always assigns numbers whether this option is enabled or - not. + The LaTeX builder always assigns numbers whether this option is enabled + or not. .. versionadded:: 1.3 @@ -376,7 +377,7 @@ General configuration A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and ``'section'`` to strings that are used for format of figure numbers. - As a special character, `%s` will be replaced to figure number. + As a special character, ``%s`` will be replaced to figure number. Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for ``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section'`` for @@ -475,6 +476,7 @@ General configuration .. versionadded:: 1.5 + Project information ------------------- @@ -514,7 +516,7 @@ Project information * Otherwise, the current time is formatted using :func:`time.strftime` and the format given in :confval:`today_fmt`. - The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d, + The default is now :confval:`today` and a :confval:`today_fmt` of ``'%B %d, %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent format for the selected locale). @@ -528,7 +530,7 @@ Project information .. versionchanged:: 1.4 The default is now ``'default'``. It is similar to ``'python3'``; - it is mostly a superset of ``'python'``. but it fallbacks to + it is mostly a superset of ``'python'`` but it fallbacks to ``'none'`` without warning if failed. ``'python3'`` and other languages will emit warning if failed. If you prefer Python 2 only highlighting, you can set it back to ``'python'``. @@ -545,7 +547,8 @@ Project information .. confval:: pygments_style The style name to use for Pygments highlighting of source code. If not set, - either the theme's default style or ``'sphinx'`` is selected for HTML output. + either the theme's default style or ``'sphinx'`` is selected for HTML + output. .. versionchanged:: 0.3 If the value is a fully-qualified name of a custom Pygments style class, @@ -580,8 +583,8 @@ Project information .. confval:: trim_footnote_reference_space - Trim spaces before footnote references that are necessary for the reST parser - to recognize the footnote, but do not look too nice in the output. + Trim spaces before footnote references that are necessary for the reST + parser to recognize the footnote, but do not look too nice in the output. .. versionadded:: 0.6 @@ -768,6 +771,7 @@ documentation on :ref:`intl` for details. .. versionchanged:: 1.5 Added ``{path}`` and ``{basename}`` tokens. + .. _html-options: Options for HTML output @@ -779,7 +783,7 @@ that use Sphinx's HTMLWriter class. .. confval:: html_theme The "theme" that the HTML output should use. See the :doc:`section about - theming `. The default is ``'alabaster'``. + theming `. The default is ``'alabaster'``. .. versionadded:: 0.6 @@ -801,11 +805,12 @@ that use Sphinx's HTMLWriter class. .. confval:: html_style - The style sheet to use for HTML pages. A file of that name must exist either - in Sphinx's :file:`static/` path, or in one of the custom paths given in - :confval:`html_static_path`. Default is the stylesheet given by the selected - theme. If you only want to add or override a few things compared to the - theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet. + The style sheet to use for HTML pages. A file of that name must exist + either in Sphinx's :file:`static/` path, or in one of the custom paths given + in :confval:`html_static_path`. Default is the stylesheet given by the + selected theme. If you only want to add or override a few things compared + to the theme's stylesheet, use CSS ``@import`` to import the theme's + stylesheet. .. confval:: html_title @@ -816,8 +821,8 @@ that use Sphinx's HTMLWriter class. .. confval:: html_short_title - A shorter "title" for the HTML docs. This is used in for links in the header - and in the HTML Help docs. If not given, it defaults to the value of + A shorter "title" for the HTML docs. This is used in for links in the + header and in the HTML Help docs. If not given, it defaults to the value of :confval:`html_title`. .. versionadded:: 0.4 @@ -910,9 +915,9 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.2 .. versionchanged:: 1.4 - The dotfiles in the extra directory will be copied to the output directory. - And it refers :confval:`exclude_patterns` on copying extra files and - directories, and ignores if path matches to patterns. + The dotfiles in the extra directory will be copied to the output + directory. And it refers :confval:`exclude_patterns` on copying extra + files and directories, and ignores if path matches to patterns. .. confval:: html_last_updated_fmt @@ -1067,12 +1072,12 @@ that use Sphinx's HTMLWriter class. .. confval:: html_use_opensearch - If nonempty, an `OpenSearch `_ description file will be - output, and all pages will contain a ```` tag referring to it. Since - OpenSearch doesn't support relative URLs for its search page location, the - value of this option must be the base URL from which these documents are - served (without trailing slash), e.g. ``"https://docs.python.org"``. The - default is ``''``. + If nonempty, an `OpenSearch `_ description + file will be output, and all pages will contain a ```` tag referring + to it. Since OpenSearch doesn't support relative URLs for its search page + location, the value of this option must be the base URL from which these + documents are served (without trailing slash), e.g. + ``"https://docs.python.org"``. The default is ``''``. .. confval:: html_file_suffix @@ -1179,18 +1184,19 @@ that use Sphinx's HTMLWriter class. The Japanese support has these options: :type: - _`type` is dotted module path string to specify Splitter implementation which - should be derived from :class:`sphinx.search.ja.BaseSplitter`. - If not specified or None is specified, ``'sphinx.search.ja.DefaultSplitter'`` will - be used. + _`type` is dotted module path string to specify Splitter implementation + which should be derived from :class:`sphinx.search.ja.BaseSplitter`. If + not specified or None is specified, + ``'sphinx.search.ja.DefaultSplitter'`` will be used. You can choose from these modules: :'sphinx.search.ja.DefaultSplitter': TinySegmenter algorithm. This is default splitter. :'sphinx.search.ja.MeCabSplitter': - MeCab binding. To use this splitter, 'mecab' python binding or dynamic link - library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required. + MeCab binding. To use this splitter, 'mecab' python binding or dynamic + link library ('libmecab.so' for linux, 'libmecab.dll' for windows) is + required. :'sphinx.search.ja.JanomeSplitter': Janome binding. To use this splitter, `Janome `_ is required. @@ -1200,7 +1206,6 @@ that use Sphinx's HTMLWriter class. To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are also acceptable. - Other option values depend on splitter value which you choose. Options for ``'mecab'``: @@ -1209,8 +1214,8 @@ that use Sphinx's HTMLWriter class. :dict: _`dict option` is the dictionary to use for the MeCab algorithm. :lib: - _`lib option` is the library name for finding the MeCab library via ctypes if - the Python binding is not installed. + _`lib option` is the library name for finding the MeCab library via + ctypes if the Python binding is not installed. For example:: @@ -1222,17 +1227,17 @@ that use Sphinx's HTMLWriter class. } Options for ``'janome'``: - :user_dic: _`user_dic option` is the user dictionary file path for Janome. + :user_dic: + _`user_dic option` is the user dictionary file path for Janome. :user_dic_enc: - _`user_dic_enc option` is the encoding for the user dictionary file specified by - ``user_dic`` option. Default is 'utf8'. + _`user_dic_enc option` is the encoding for the user dictionary file + specified by ``user_dic`` option. Default is 'utf8'. .. versionadded:: 1.1 .. versionchanged:: 1.4 - html_search_options for Japanese is re-organized and any custom splitter can be - used by `type`_ settings. - + html_search_options for Japanese is re-organized and any custom splitter + can be used by `type`_ settings. The Chinese support has these options: @@ -1258,10 +1263,12 @@ that use Sphinx's HTMLWriter class. .. confval:: html_experimental_html5_writer - Output is processed with HTML5 writer. This feature needs docutils 0.13 or newer. Default is ``False``. + Output is processed with HTML5 writer. This feature needs docutils 0.13 or + newer. Default is ``False``. .. versionadded:: 1.6 + .. _htmlhelp-options: Options for HTML help output @@ -1271,6 +1278,7 @@ Options for HTML help output Output file base name for HTML help builder. Default is ``'pydoc'``. + .. _applehelp-options: Options for Apple Help output @@ -1316,8 +1324,8 @@ HTML builder, so the HTML options also apply where appropriate. .. confval:: applehelp_icon - The help bundle icon file, or ``None`` for no icon. According to Apple’s - documentation, this should be a 16-by-16 pixel version of the application’s + The help bundle icon file, or ``None`` for no icon. According to Apple's + documentation, this should be a 16-by-16 pixel version of the application's icon with a transparent background, saved as a PNG file. .. confval:: applehelp_kb_product @@ -1331,14 +1339,14 @@ HTML builder, so the HTML options also apply where appropriate. e.g. ``https://example.com/kbsearch.py?p='product'&q='query'&l='lang'``. Help Viewer will replace the values ``'product'``, ``'query'`` and ``'lang'`` at runtime with the contents of :confval:`applehelp_kb_product`, - the text entered by the user in the search box and the user’s system + the text entered by the user in the search box and the user's system language respectively. Defaults to ``None`` for no remote search. .. confval:: applehelp_remote_url - The URL for remote content. You can place a copy of your Help Book’s + The URL for remote content. You can place a copy of your Help Book's ``Resources`` folder at this location and Help Viewer will attempt to use it to fetch updated content. @@ -1453,8 +1461,8 @@ the `Dublin Core metadata `_. The HTML theme for the epub output. Since the default themes are not optimized for small screen space, using the same theme for HTML and epub - output is usually not wise. This defaults to ``'epub'``, a theme designed to - save visual space. + output is usually not wise. This defaults to ``'epub'``, a theme designed + to save visual space. .. confval:: epub_theme_options @@ -1501,9 +1509,9 @@ the `Dublin Core metadata `_. .. confval:: epub_publisher - The publisher of the document. This is put in the Dublin Core metadata. You - may use any sensible string, e.g. the project homepage. The defaults to the - :confval:`author` option. + The publisher of the document. This is put in the Dublin Core metadata. + You may use any sensible string, e.g. the project homepage. The defaults to + the :confval:`author` option. .. confval:: epub_copyright @@ -1528,9 +1536,9 @@ the `Dublin Core metadata `_. A unique identifier for the document. This is put in the Dublin Core metadata. You may use a - `XML's Name format `_ string. - You can't use hyphen, period, numbers as a first character. - The default value is ``'unknown'``. + `XML's Name format `_ + string. You can't use hyphen, period, numbers as a first character. The + default value is ``'unknown'``. .. confval:: epub_cover @@ -1684,12 +1692,14 @@ the `Dublin Core metadata `_. .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode + .. _latex-options: Options for LaTeX output ------------------------ -These options influence LaTeX output. See further :doc:`latex`. +These options influence LaTeX output. Refer to :doc:`/latex` for more +information. .. confval:: latex_engine @@ -1737,7 +1747,8 @@ These options influence LaTeX output. See further :doc:`latex`. they are to be inserted literally. * *author*: Author for the LaTeX document. The same LaTeX markup caveat as for *title* applies. Use ``\\and`` to separate multiple authors, as in: - ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX). + ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach + LaTeX). * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided by Sphinx and based on ``'report'``, resp. ``'article'``; Japanese documents use ``'jsbook'``, resp. ``'jreport'``.) "howto" (non-Japanese) @@ -1749,7 +1760,8 @@ These options influence LaTeX output. See further :doc:`latex`. * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff - in the master document that shows up in the HTML, but not the LaTeX output. + in the master document that shows up in the HTML, but not the LaTeX + output. .. versionadded:: 1.2 In the past including your own document class required you to prepend the @@ -1846,29 +1858,34 @@ These options influence LaTeX output. See further :doc:`latex`. ``'papersize'`` Paper size option of the document class (``'a4paper'`` or ``'letterpaper'``), default ``'letterpaper'``. + ``'pointsize'`` Point size option of the document class (``'10pt'``, ``'11pt'`` or ``'12pt'``), default ``'10pt'``. + ``'pxunit'`` the value of the ``px`` when used in image attributes ``width`` and ``height``. The default value is ``'0.75bp'`` which achieves ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter leads to TeX computing a more precise value, due to the smaller unit - used in the specification); for ``72px=1in``, - simply use ``'1bp'``; for ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``. + used in the specification); for ``72px=1in``, simply use ``'1bp'``; for + ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``. .. versionadded:: 1.5 + ``'sphinxsetup'`` A comma separated list of ``key=value`` package options for the Sphinx - LaTeX style, default empty. See :doc:`latex`. + LaTeX style, default empty. See :doc:`/latex`. .. versionadded:: 1.5 + ``'passoptionstopackages'`` A string which will be positioned early in the preamble, designed to contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty. .. versionadded:: 1.4 + ``'babel'`` "babel" package inclusion, default ``'\\usepackage{babel}'`` (the suitable document language string is passed as class option, and @@ -1880,6 +1897,7 @@ These options influence LaTeX output. See further :doc:`latex`. is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. .. versionchanged:: 1.6 ``'lualatex'`` uses same default setting as ``'xelatex'`` + ``'fontpkg'`` Font package inclusion, default ``'\\usepackage{times}'`` (which uses Times for text, Helvetica for sans serif and Courier for code-blocks). @@ -1909,12 +1927,15 @@ These options influence LaTeX output. See further :doc:`latex`. the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to ``''`` to disable fncychap. + ``'preamble'`` - Additional preamble content, default empty. See :doc:`latex`. + Additional preamble content, default empty. See :doc:`/latex`. + ``'atendofbody'`` Additional document content (right before the indices), default empty. .. versionadded:: 1.5 + ``'figure_align'`` Latex figure float alignment, default 'htbp' (here, top, bottom, page). Whenever an image doesn't fit into the current page, it will be @@ -1923,6 +1944,7 @@ These options influence LaTeX output. See further :doc:`latex`. and position figures strictly in the order they appear in the source. .. versionadded:: 1.3 + ``'footer'`` Additional footer content (before the indices), default empty. @@ -1939,6 +1961,7 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.2 .. versionchanged:: 1.6 Added this documentation. + ``'maxlistdepth'`` LaTeX allows by default at most 6 levels for nesting list and quote-like environments, with at most 4 enumerated lists, and 4 bullet @@ -1956,6 +1979,7 @@ These options influence LaTeX output. See further :doc:`latex`. dedicated commands of this LaTeX package. .. versionadded:: 1.5 + ``'inputenc'`` "inputenc" package inclusion, defaults to ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex. @@ -1964,10 +1988,12 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionchanged:: 1.4.3 Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all compilers. + ``'cmappkg'`` "cmap" package inclusion, default ``'\\usepackage{cmap}'``. .. versionadded:: 1.2 + ``'fontenc'`` "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``. @@ -1976,6 +2002,7 @@ These options influence LaTeX output. See further :doc:`latex`. :confval:`latex_engine` is ``'xelatex'``. .. versionchanged:: 1.6 ``'lualatex'`` also uses ``fontspec`` per default. + ``'geometry'`` "geometry" package inclusion, the default definition is: @@ -2006,6 +2033,7 @@ These options influence LaTeX output. See further :doc:`latex`. width will be set to an integer multiple of the *zenkaku* width, and the text height to an integer multiple of the baseline. See the :ref:`hmargin ` documentation for more. + ``'hyperref'`` "hyperref" package inclusion; also loads package "hypcap" and issues ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is @@ -2017,15 +2045,17 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.5 Previously this was done from inside :file:`sphinx.sty`. + ``'maketitle'`` "maketitle" call, default ``'\\maketitle'`` (but it has been redefined by the Sphinx ``manual`` and ``howto`` classes.) Override - if you want to - generate a differently-styled title page. + if you want to generate a differently-styled title page. + ``'releasename'`` value that prefixes ``'release'`` element on title page, default ``'Release'``. As for *title* and *author* used in the tuples of :confval:`latex_documents`, it is inserted as LaTeX markup. + ``'tableofcontents'`` "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a wrapper of unmodified ``\tableofcontents``, which may itself be @@ -2038,6 +2068,7 @@ These options influence LaTeX output. See further :doc:`latex`. Previously the meaning of ``\tableofcontents`` itself was modified by Sphinx. This created an incompatibility with dedicated packages modifying it also such as "tocloft" or "etoc". + ``'transition'`` Commands used to display transitions, default ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``. Override if you want to @@ -2046,12 +2077,14 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.2 .. versionchanged:: 1.6 Remove unneeded ``{}`` after ``\\hrule``. + ``'printindex'`` "printindex" call, the last thing in the file, default ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. For example ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the index is full of long entries. + ``'fvset'`` Customization of ``fancyvrb`` LaTeX package. Defaults to ``'\\fvset{fontsize=\\small}'``, because default font (Courier) used in @@ -2062,6 +2095,7 @@ These options influence LaTeX output. See further :doc:`latex`. one unified typeface family (Latin Modern OpenType). .. versionadded:: 1.8 + * Keys that are set by other options and therefore should not be overridden are: @@ -2090,19 +2124,20 @@ These options influence LaTeX output. See further :doc:`latex`. .. confval:: latex_additional_files - A list of file names, relative to the configuration directory, to copy to the - build directory when building LaTeX output. This is useful to copy files - that Sphinx doesn't copy automatically, e.g. if they are referenced in custom - LaTeX added in ``latex_elements``. Image files that are referenced in source - files (e.g. via ``.. image::``) are copied automatically. + A list of file names, relative to the configuration directory, to copy to + the build directory when building LaTeX output. This is useful to copy + files that Sphinx doesn't copy automatically, e.g. if they are referenced in + custom LaTeX added in ``latex_elements``. Image files that are referenced + in source files (e.g. via ``.. image::``) are copied automatically. - You have to make sure yourself that the filenames don't collide with those of - any automatically copied files. + You have to make sure yourself that the filenames don't collide with those + of any automatically copied files. .. versionadded:: 0.6 .. versionchanged:: 1.2 - This overrides the files which is provided from Sphinx such as sphinx.sty. + This overrides the files which is provided from Sphinx such as + ``sphinx.sty``. .. _text-options: @@ -2144,8 +2179,8 @@ These options influence text output. .. confval:: text_secnumber_suffix - Suffix for section numbers in text output. Default: ``". "``. Set to ``" "`` - to suppress the final dot on section numbers. + Suffix for section numbers in text output. Default: ``". "``. Set to + ``" "`` to suppress the final dot on section numbers. .. versionadded:: 1.7 @@ -2163,20 +2198,27 @@ These options influence manual page output. must be a list of tuples ``(startdocname, name, description, authors, section)``, where the items are: - * *startdocname*: document name that is the "root" of the manual page. All - documents referenced by it in TOC trees will be included in the manual file - too. (If you want one master manual page, use your :confval:`master_doc` - here.) - * *name*: name of the manual page. This should be a short string without - spaces or special characters. It is used to determine the file name as - well as the name of the manual page (in the NAME section). - * *description*: description of the manual page. This is used in the NAME - section. - * *authors*: A list of strings with authors, or a single string. Can be an - empty string or list if you do not want to automatically generate an - AUTHORS section in the manual page. - * *section*: The manual page section. Used for the output file name as well - as in the manual page header. + *startdocname* + Document name that is the "root" of the manual page. All documents + referenced by it in TOC trees will be included in the manual file too. + (If you want one master manual page, use your :confval:`master_doc` here.) + + *name* + Name of the manual page. This should be a short string without spaces or + special characters. It is used to determine the file name as well as the + name of the manual page (in the NAME section). + + *description* + Description of the manual page. This is used in the NAME section. + + *authors* + A list of strings with authors, or a single string. Can be an empty + string or list if you do not want to automatically generate an AUTHORS + section in the manual page. + + *section* + The manual page section. Used for the output file name as well as in the + manual page header. .. versionadded:: 1.0 @@ -2201,27 +2243,38 @@ These options influence Texinfo output. author, dir_entry, description, category, toctree_only)``, where the items are: - * *startdocname*: document name that is the "root" of the Texinfo file. All - documents referenced by it in TOC trees will be included in the Texinfo - file too. (If you want only one Texinfo file, use your - :confval:`master_doc` here.) - * *targetname*: file name (no extension) of the Texinfo file in the output - directory. - * *title*: Texinfo document title. Can be empty to use the title of the - *startdoc*. Inserted as Texinfo markup, so special characters like @ and - {} will need to be escaped to be inserted literally. - * *author*: Author for the Texinfo document. Inserted as Texinfo markup. - Use ``@*`` to separate multiple authors, as in: ``'John@*Sarah'``. - * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file. - * *description*: Descriptive text to appear in the top-level ``DIR`` menu - file. - * *category*: Specifies the section which this entry will appear in the - top-level ``DIR`` menu file. - * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* - document itself is not included in the output, only the documents - referenced by it via TOC trees. With this option, you can put extra stuff - in the master document that shows up in the HTML, but not the Texinfo - output. + *startdocname* + Document name that is the "root" of the Texinfo file. All documents + referenced by it in TOC trees will be included in the Texinfo file too. + (If you want only one Texinfo file, use your :confval:`master_doc` here.) + + *targetname* + File name (no extension) of the Texinfo file in the output directory. + + *title* + Texinfo document title. Can be empty to use the title of the *startdoc*. + Inserted as Texinfo markup, so special characters like ``@`` and ``{}`` + will need to be escaped to be inserted literally. + + *author* + Author for the Texinfo document. Inserted as Texinfo markup. Use ``@*`` + to separate multiple authors, as in: ``'John@*Sarah'``. + + *dir_entry* + The name that will appear in the top-level ``DIR`` menu file. + + *description* + Descriptive text to appear in the top-level ``DIR`` menu file. + + *category* + Specifies the section which this entry will appear in the top-level + ``DIR`` menu file. + + *toctree_only* + Must be ``True`` or ``False``. If true, the *startdoc* document itself is + not included in the output, only the documents referenced by it via TOC + trees. With this option, you can put extra stuff in the master document + that shows up in the HTML, but not the Texinfo output. .. versionadded:: 1.1 @@ -2307,7 +2360,8 @@ builder, the HTML options also apply where appropriate. .. confval:: qthelp_basename - The basename for the qthelp file. It defaults to the :confval:`project` name. + The basename for the qthelp file. It defaults to the :confval:`project` + name. .. confval:: qthelp_namespace @@ -2372,7 +2426,7 @@ Options for the linkcheck builder A list of regular expressions that match URIs that should skip checking the validity of anchors in links. This allows skipping entire sites, where anchors are used to control dynamic pages, or just specific anchors within - a page, where javascript is used to add anchors dynamically, or use the + a page, where JavaScript is used to add anchors dynamically, or use the fragment as part of to trigger an internal REST request. Default is ``["/#!"]``. @@ -2393,8 +2447,8 @@ Options for the XML builder .. [1] A note on available globbing syntax: you can use the standard shell constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that - these all don't match slashes. A double star ``**`` can be used to match - any sequence of characters *including* slashes. + these all don't match slashes. A double star ``**`` can be used to + match any sequence of characters *including* slashes. .. _cpp-config: @@ -2404,27 +2458,30 @@ Options for the C++ domain .. confval:: cpp_index_common_prefix - A list of prefixes that will be ignored when sorting C++ objects in the global index. - For example ``['awesome_lib::']``. + A list of prefixes that will be ignored when sorting C++ objects in the + global index. For example ``['awesome_lib::']``. .. versionadded:: 1.5 .. confval:: cpp_id_attributes A list of strings that the parser additionally should accept as attributes. - This can for example be used when attributes have been ``#define`` d for portability. + This can for example be used when attributes have been ``#define`` d for + portability. .. versionadded:: 1.5 .. confval:: cpp_paren_attributes - A list of strings that the parser additionally should accept as attributes with one argument. - That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute - for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``). - This can for example be used when attributes have been ``#define`` d for portability. + A list of strings that the parser additionally should accept as attributes + with one argument. That is, if ``my_align_as`` is in the list, then + ``my_align_as(X)`` is parsed as an attribute for all strings ``X`` that have + balanced brances (``()``, ``[]``, and ``{}``). This can for example be used + when attributes have been ``#define`` d for portability. .. versionadded:: 1.5 + Example of configuration file ============================= From 16e76faba397a085a92eb3d1588b92ff456af045 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 26 Feb 2018 11:49:23 +0000 Subject: [PATCH 11/25] doc: Add "config" to usage guide Signed-off-by: Stephen Finucane --- doc/contents.rst | 2 +- doc/{config.rst => usage/configuration.rst} | 2 +- doc/usage/quickstart.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename doc/{config.rst => usage/configuration.rst} (99%) diff --git a/doc/contents.rst b/doc/contents.rst index 4a8a4d947..77dcf6c42 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -11,11 +11,11 @@ Sphinx documentation contents usage/quickstart usage/restructuredtext/index usage/markdown + usage/configuration intro man/index builders - config intl theming setuptools diff --git a/doc/config.rst b/doc/usage/configuration.rst similarity index 99% rename from doc/config.rst rename to doc/usage/configuration.rst index 27d84b293..02df9215d 100644 --- a/doc/config.rst +++ b/doc/usage/configuration.rst @@ -2485,5 +2485,5 @@ Options for the C++ domain Example of configuration file ============================= -.. literalinclude:: _static/conf.py.txt +.. literalinclude:: ../_static/conf.py.txt :language: python diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index adda610ab..e90b993c6 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -236,8 +236,8 @@ so on. The file is saved in UTF-8 by default, as indicated by the encoding declaration in the first line. If you use non-ASCII characters in any string value, you need to use Python Unicode strings (like ``project = u'Exposé'``). -|more| See :ref:`build-config` for documentation of all available config -values. +|more| See :doc:`/usage/configuration` for documentation of all available +config values. .. todo:: Move this entire doc to a different section From 0bf8886fc4caa182d9006167dcbfe9b6da60619d Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 30 Apr 2018 10:21:34 +0100 Subject: [PATCH 12/25] doc: Address review comments These came up in the review for pull request #4799. Signed-off-by: Stephen Finucane --- doc/usage/configuration.rst | 2 +- doc/usage/markdown.rst | 30 +++++++++++++++++------------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 02df9215d..948a9ffbc 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2485,5 +2485,5 @@ Options for the C++ domain Example of configuration file ============================= -.. literalinclude:: ../_static/conf.py.txt +.. literalinclude:: /_static/conf.py.txt :language: python diff --git a/doc/usage/markdown.rst b/doc/usage/markdown.rst index 2855eb8f2..f67b94cbd 100644 --- a/doc/usage/markdown.rst +++ b/doc/usage/markdown.rst @@ -1,21 +1,28 @@ .. highlight:: python +.. _markdown: + ======== Markdown ======== -`Markdown`_ is a lightweight markup language with a simplistic plain text +`Markdown`__ is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different *flavors*. To -support Markdown-based documentation, Sphinx can use `recommonmark`_. -recommonmark is a Docutils bridge to `CommonMark-py`_, a Python package for -parsing the `CommonMark`_ Markdown flavor. +support Markdown-based documentation, Sphinx can use `recommonmark`__. +recommonmark is a Docutils bridge to `CommonMark-py`__, a Python package for +parsing the `CommonMark`__ Markdown flavor. + +__ https://daringfireball.net/projects/markdown/ +__ https://recommonmark.readthedocs.io/en/latest/index.html +__ https://github.com/rtfd/CommonMark-py +__ http://commonmark.org/ Configuration ------------- To configure your Sphinx project for Markdown support, proceed as follows: -#. Install recommonmark:: +#. Install *recommonmark*:: pip install recommonmark @@ -26,18 +33,15 @@ To configure your Sphinx project for Markdown support, proceed as follows: '.md': 'recommonmark.parser.CommonMarkParser', } - You can replace `.md` with a filename extension of your choice. + You can replace ``.md`` with a filename extension of your choice. #. Add the Markdown filename extension to the ``source_suffix`` configuration variable:: source_suffix = ['.rst', '.md'] -#. You can further configure recommonmark to allow custom syntax that standard - CommonMark doesn't support. Read more in the `recommonmark documentation - `__. +#. You can further configure *recommonmark* to allow custom syntax that + standard *CommonMark* doesn't support. Read more in the `recommonmark + documentation`__. -.. _Markdown: https://daringfireball.net/projects/markdown/ -.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html -.. _CommonMark-py: -.. _CommonMark: http://commonmark.org/ +__ https://recommonmark.readthedocs.io/en/latest/auto_structify.html From 722a59d4591888e0493264a112dd6e45f8c8fed2 Mon Sep 17 00:00:00 2001 From: mondeja Date: Tue, 1 May 2018 15:52:58 +0200 Subject: [PATCH 13/25] Specify version in README.rst readthedocs shield Readthedocs status is shown as `docs unknown` before this change because any version is specified on image url. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 85255f946..9d9ffba6e 100644 --- a/README.rst +++ b/README.rst @@ -6,7 +6,7 @@ :target: https://pypi.org/project/Sphinx/ :alt: Package on PyPi -.. image:: https://readthedocs.org/projects/sphinx/badge/ +.. image:: https://readthedocs.org/projects/sphinx/badge/?version=master :target: http://www.sphinx-doc.org/ :alt: Documentation Status From cbe2b66001be6b3519149113313508d3c4ae847b Mon Sep 17 00:00:00 2001 From: Dennis Wegner Date: Tue, 1 May 2018 15:57:49 +0200 Subject: [PATCH 14/25] Fixed the HTML search for uppercase words in all languages After testing the search for all uppercase words like `PAR_APP_TITLE` with different settings for `language` in `conf.py` I applied the same fix as in PR #4871 to all other languages. English, French and German were already fixed. --- sphinx/search/da.py | 2 +- sphinx/search/es.py | 2 +- sphinx/search/fi.py | 2 +- sphinx/search/hu.py | 2 +- sphinx/search/it.py | 2 +- sphinx/search/nl.py | 2 +- sphinx/search/no.py | 2 +- sphinx/search/pt.py | 2 +- sphinx/search/ro.py | 2 +- sphinx/search/ru.py | 2 +- sphinx/search/sv.py | 2 +- sphinx/search/tr.py | 2 +- sphinx/search/zh.py | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/sphinx/search/da.py b/sphinx/search/da.py index b3611152a..8b7ad2502 100644 --- a/sphinx/search/da.py +++ b/sphinx/search/da.py @@ -128,4 +128,4 @@ class SearchDanish(SearchLanguage): self.stemmer = snowballstemmer.stemmer('danish') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/es.py b/sphinx/search/es.py index 2777811d8..c18b97da0 100644 --- a/sphinx/search/es.py +++ b/sphinx/search/es.py @@ -371,4 +371,4 @@ class SearchSpanish(SearchLanguage): self.stemmer = snowballstemmer.stemmer('spanish') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/fi.py b/sphinx/search/fi.py index ca63b0021..612d204be 100644 --- a/sphinx/search/fi.py +++ b/sphinx/search/fi.py @@ -121,4 +121,4 @@ class SearchFinnish(SearchLanguage): self.stemmer = snowballstemmer.stemmer('finnish') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/hu.py b/sphinx/search/hu.py index 85d15bac7..c8deab97d 100644 --- a/sphinx/search/hu.py +++ b/sphinx/search/hu.py @@ -235,4 +235,4 @@ class SearchHungarian(SearchLanguage): self.stemmer = snowballstemmer.stemmer('hungarian') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/it.py b/sphinx/search/it.py index b613ce33c..7351f3373 100644 --- a/sphinx/search/it.py +++ b/sphinx/search/it.py @@ -324,4 +324,4 @@ class SearchItalian(SearchLanguage): self.stemmer = snowballstemmer.stemmer('italian') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/nl.py b/sphinx/search/nl.py index b2ab4e0f0..909527449 100644 --- a/sphinx/search/nl.py +++ b/sphinx/search/nl.py @@ -135,4 +135,4 @@ class SearchDutch(SearchLanguage): self.stemmer = snowballstemmer.stemmer('dutch') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/no.py b/sphinx/search/no.py index 32f7b38c5..3b68f4e7c 100644 --- a/sphinx/search/no.py +++ b/sphinx/search/no.py @@ -210,4 +210,4 @@ class SearchNorwegian(SearchLanguage): self.stemmer = snowballstemmer.stemmer('norwegian') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/pt.py b/sphinx/search/pt.py index ba9f2529b..170ee01f9 100644 --- a/sphinx/search/pt.py +++ b/sphinx/search/pt.py @@ -270,4 +270,4 @@ class SearchPortuguese(SearchLanguage): self.stemmer = snowballstemmer.stemmer('portuguese') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/ro.py b/sphinx/search/ro.py index b4beced2d..69d6edd8e 100644 --- a/sphinx/search/ro.py +++ b/sphinx/search/ro.py @@ -36,4 +36,4 @@ class SearchRomanian(SearchLanguage): def stem(self, word): # type: (unicode) -> unicode - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/ru.py b/sphinx/search/ru.py index 8eb6c3dbb..0cdb4bb61 100644 --- a/sphinx/search/ru.py +++ b/sphinx/search/ru.py @@ -259,4 +259,4 @@ class SearchRussian(SearchLanguage): self.stemmer = snowballstemmer.stemmer('russian') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/sv.py b/sphinx/search/sv.py index 64883381e..186b56a3e 100644 --- a/sphinx/search/sv.py +++ b/sphinx/search/sv.py @@ -148,4 +148,4 @@ class SearchSwedish(SearchLanguage): self.stemmer = snowballstemmer.stemmer('swedish') def stem(self, word): - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/tr.py b/sphinx/search/tr.py index 4ce42dd76..1b8a0f94f 100644 --- a/sphinx/search/tr.py +++ b/sphinx/search/tr.py @@ -36,4 +36,4 @@ class SearchTurkish(SearchLanguage): def stem(self, word): # type: (unicode) -> unicode - return self.stemmer.stemWord(word) + return self.stemmer.stemWord(word.lower()) diff --git a/sphinx/search/zh.py b/sphinx/search/zh.py index 2301e1103..6c5b65d6b 100644 --- a/sphinx/search/zh.py +++ b/sphinx/search/zh.py @@ -259,4 +259,4 @@ class SearchChinese(SearchLanguage): def stem(self, word): # type: (unicode) -> unicode - return self.stemmer.stem(word) + return self.stemmer.stem(word.lower()) From 90949a3b4fab5b2cd5d2a84980413bbd74d0cc88 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 22 Apr 2018 12:36:52 +0900 Subject: [PATCH 15/25] refactor: Move env.read_doc() to Builder._read_doc() --- CHANGES | 1 + doc/extdev/index.rst | 5 +++++ sphinx/builders/__init__.py | 35 ++++++++++++++++++++++++++++--- sphinx/environment/__init__.py | 38 +++++++--------------------------- 4 files changed, 46 insertions(+), 33 deletions(-) diff --git a/CHANGES b/CHANGES index 1b8645501..f24a82a4b 100644 --- a/CHANGES +++ b/CHANGES @@ -51,6 +51,7 @@ Deprecated * ``Config.check_unicode()`` is deprecated * ``sphinx.application.CONFIG_FILENAME`` is deprecated * ``highlightlang`` directive is deprecated +* ``env.read_doc()`` is deprecated For more details, see `deprecation APIs list `_ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 3a2e7bc25..842f34073 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -203,6 +203,11 @@ The following is a list of deprecated interface. - 3.0 - ``Builder.read()`` + * - ``BuildEnvironment.read_doc()`` + - 1.8 + - 3.0 + - ``Builder.read_doc()`` + * - ``BuildEnvironment._read_serial()`` - 1.8 - 3.0 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index fb171dcde..d5be2a689 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -9,6 +9,7 @@ :license: BSD, see LICENSE for details. """ +import time import warnings from os import path @@ -18,10 +19,12 @@ from sphinx.deprecation import RemovedInSphinx20Warning from sphinx.environment import BuildEnvironment from sphinx.environment.adapters.asset import ImageAdapter from sphinx.errors import SphinxError +from sphinx.io import read_doc from sphinx.locale import __ -from sphinx.util import i18n, import_object, logging, status_iterator +from sphinx.util import i18n, import_object, logging, rst, status_iterator from sphinx.util.build_phase import BuildPhase from sphinx.util.console import bold # type: ignore +from sphinx.util.docutils import sphinx_domains from sphinx.util.i18n import find_catalog from sphinx.util.osutil import SEP, ensuredir, relative_uri, relpath from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \ @@ -478,7 +481,7 @@ class Builder(object): # remove all inventory entries for that file self.app.emit('env-purge-doc', self.env, docname) self.env.clear_doc(docname) - self.env.read_doc(docname, self.app) + self.read_doc(docname) def _read_parallel(self, docnames, nproc): # type: (List[unicode], int) -> None @@ -491,7 +494,7 @@ class Builder(object): # type: (List[unicode]) -> unicode self.env.app = self.app for docname in docs: - self.env.read_doc(docname, self.app) + self.read_doc(docname) # allow pickling self to send it back return BuildEnvironment.dumps(self.env) @@ -511,6 +514,32 @@ class Builder(object): logger.info(bold('waiting for workers...')) tasks.join() + def read_doc(self, docname): + # type: (unicode) -> None + """Parse a file and add/update inventory entries for the doctree.""" + self.env.prepare_settings(docname) + + # Add confdir/docutils.conf to dependencies list if exists + docutilsconf = path.join(self.confdir, 'docutils.conf') + if path.isfile(docutilsconf): + self.env.note_dependency(docutilsconf) + + with sphinx_domains(self.env), rst.default_role(docname, self.config.default_role): + doctree = read_doc(self.app, self.env, self.env.doc2path(docname)) + + # store time of reading, for outdated files detection + # (Some filesystems have coarse timestamp resolution; + # therefore time.time() can be older than filesystem's timestamp. + # For example, FAT32 has 2sec timestamp resolution.) + self.env.all_docs[docname] = max(time.time(), + path.getmtime(self.env.doc2path(docname))) + + # cleanup + self.env.temp_data.clear() + self.env.ref_context.clear() + + self.env.write_doctree(docname, doctree) + def write(self, build_docnames, updated_docnames, method='update'): # type: (Iterable[unicode], Sequence[unicode], unicode) -> None if build_docnames is None or build_docnames == ['__all__']: diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index f69a44d76..f745b81c7 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -12,7 +12,6 @@ import os import re import sys -import time import types import warnings from collections import defaultdict @@ -28,12 +27,11 @@ from sphinx.deprecation import RemovedInSphinx20Warning, RemovedInSphinx30Warnin from sphinx.environment.adapters.indexentries import IndexEntries from sphinx.environment.adapters.toctree import TocTree from sphinx.errors import SphinxError, ExtensionError -from sphinx.io import read_doc from sphinx.locale import __ from sphinx.transforms import SphinxTransformer from sphinx.util import get_matching_docs, FilenameUniqDict -from sphinx.util import logging, rst -from sphinx.util.docutils import sphinx_domains, WarningStream +from sphinx.util import logging +from sphinx.util.docutils import WarningStream from sphinx.util.i18n import find_catalog_files from sphinx.util.matching import compile_matchers from sphinx.util.nodes import is_translatable @@ -555,32 +553,6 @@ class BuildEnvironment(object): self.temp_data['default_domain'] = \ self.domains.get(self.config.primary_domain) - def read_doc(self, docname, app=None): - # type: (unicode, Sphinx) -> None - """Parse a file and add/update inventory entries for the doctree.""" - self.prepare_settings(docname) - - # Add confdir/docutils.conf to dependencies list if exists - docutilsconf = path.join(self.app.confdir, 'docutils.conf') - if path.isfile(docutilsconf): - self.note_dependency(docutilsconf) - - with sphinx_domains(self), rst.default_role(docname, self.config.default_role): - doctree = read_doc(self.app, self, self.doc2path(docname)) - - # store time of reading, for outdated files detection - # (Some filesystems have coarse timestamp resolution; - # therefore time.time() can be older than filesystem's timestamp. - # For example, FAT32 has 2sec timestamp resolution.) - self.all_docs[docname] = max( - time.time(), path.getmtime(self.doc2path(docname))) - - # cleanup - self.temp_data.clear() - self.ref_context.clear() - - self.write_doctree(docname, doctree) - # utilities to use while reading a document @property @@ -847,6 +819,12 @@ class BuildEnvironment(object): RemovedInSphinx30Warning) return self.app.builder._read_parallel(docnames, nproc) + def read_doc(self, docname, app=None): + # type: (unicode, Sphinx) -> None + warnings.warn('env.read_doc() is deprecated. Please use builder.read_doc() instead.', + RemovedInSphinx30Warning) + self.app.builder.read_doc(docname) + @property def _nitpick_ignore(self): # type: () -> List[unicode] From 39fe7ee29369ce8e0deb815de0dadb561525ddab Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 22 Apr 2018 13:22:42 +0900 Subject: [PATCH 16/25] refactor: Move env.write_doctree() to Builder._write_doctree() --- CHANGES | 1 + doc/extdev/index.rst | 5 +++++ sphinx/builders/__init__.py | 18 +++++++++++++++++- sphinx/environment/__init__.py | 24 ++++++++---------------- 4 files changed, 31 insertions(+), 17 deletions(-) diff --git a/CHANGES b/CHANGES index f24a82a4b..fb965a3d0 100644 --- a/CHANGES +++ b/CHANGES @@ -52,6 +52,7 @@ Deprecated * ``sphinx.application.CONFIG_FILENAME`` is deprecated * ``highlightlang`` directive is deprecated * ``env.read_doc()`` is deprecated +* ``env.write_doctree()`` is deprecated For more details, see `deprecation APIs list `_ diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 842f34073..2dad3e652 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -218,6 +218,11 @@ The following is a list of deprecated interface. - 3.0 - ``Builder.read()`` + * - ``BuildEnvironment.write_doctree()`` + - 1.8 + - 3.0 + - ``Builder.write_doctree()`` + * - ``sphinx.locale.l_()`` - 1.8 - 3.0 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index d5be2a689..841489704 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -14,6 +14,7 @@ import warnings from os import path from docutils import nodes +from six.moves import cPickle as pickle from sphinx.deprecation import RemovedInSphinx20Warning from sphinx.environment import BuildEnvironment @@ -538,7 +539,22 @@ class Builder(object): self.env.temp_data.clear() self.env.ref_context.clear() - self.env.write_doctree(docname, doctree) + self.write_doctree(docname, doctree) + + def write_doctree(self, docname, doctree): + # type: (unicode, nodes.Node) -> None + """Write the doctree to a file.""" + # make it picklable + doctree.reporter = None + doctree.transformer = None + doctree.settings.warning_stream = None + doctree.settings.env = None + doctree.settings.record_dependencies = None + + doctree_filename = self.env.doc2path(docname, self.env.doctreedir, '.doctree') + ensuredir(path.dirname(doctree_filename)) + with open(doctree_filename, 'wb') as f: + pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) def write(self, build_docnames, updated_docnames, method='update'): # type: (Iterable[unicode], Sequence[unicode], unicode) -> None diff --git a/sphinx/environment/__init__.py b/sphinx/environment/__init__.py index f745b81c7..e8d9dd9d4 100644 --- a/sphinx/environment/__init__.py +++ b/sphinx/environment/__init__.py @@ -35,7 +35,7 @@ from sphinx.util.docutils import WarningStream from sphinx.util.i18n import find_catalog_files from sphinx.util.matching import compile_matchers from sphinx.util.nodes import is_translatable -from sphinx.util.osutil import SEP, ensuredir, relpath +from sphinx.util.osutil import SEP, relpath from sphinx.util.websupport import is_commentable if False: @@ -655,21 +655,6 @@ class BuildEnvironment(object): doctree.reporter = Reporter(self.doc2path(docname), 2, 5, stream=WarningStream()) return doctree - def write_doctree(self, docname, doctree): - # type: (unicode, nodes.Node) -> None - """Write the doctree to a file.""" - # make it picklable - doctree.reporter = None - doctree.transformer = None - doctree.settings.warning_stream = None - doctree.settings.env = None - doctree.settings.record_dependencies = None - - doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') - ensuredir(path.dirname(doctree_filename)) - with open(doctree_filename, 'wb') as f: - pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) - def get_and_resolve_doctree(self, docname, builder, doctree=None, prune_toctrees=True, includehidden=False): # type: (unicode, Builder, nodes.Node, bool, bool) -> nodes.Node @@ -825,6 +810,13 @@ class BuildEnvironment(object): RemovedInSphinx30Warning) self.app.builder.read_doc(docname) + def write_doctree(self, docname, doctree): + # type: (unicode, nodes.Node) -> None + warnings.warn('env.write_doctree() is deprecated. ' + 'Please use builder.write_doctree() instead.', + RemovedInSphinx30Warning) + self.app.builder.write_doctree(docname, doctree) + @property def _nitpick_ignore(self): # type: () -> List[unicode] From 606dccec6ada96004825ed1972b742078e17ddbb Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 2 May 2018 01:50:19 +0900 Subject: [PATCH 17/25] Optimize copy_asset() Instantiate default renderer object only once to reduce the cost. --- sphinx/util/fileutil.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sphinx/util/fileutil.py b/sphinx/util/fileutil.py index 7caf40275..fcbc8abe6 100644 --- a/sphinx/util/fileutil.py +++ b/sphinx/util/fileutil.py @@ -74,6 +74,10 @@ def copy_asset(source, destination, excluded=lambda path: False, context=None, r if not os.path.exists(source): return + if renderer is None: + from sphinx.util.template import SphinxRenderer + renderer = SphinxRenderer() + ensuredir(destination) if os.path.isfile(source): copy_asset_file(source, destination, context, renderer) From 9f9288ebe77d3cd55217e8ee3faab24c9b5ff3d2 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 1 May 2018 23:41:57 +0900 Subject: [PATCH 18/25] Fix URLs for css in Windows --- sphinx/builders/html.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 25538ac17..7e6475980 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -355,7 +355,7 @@ class StandaloneHTMLBuilder(Builder): continue if '://' not in filename: - filename = path.join('_static', filename) + filename = posixpath.join('_static', filename) self.css_files.append(Stylesheet(filename, **attrs)) # type: ignore From cb831bb70330f851cd37db953beb88653f7f2465 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 2 May 2018 01:58:57 +0900 Subject: [PATCH 19/25] qthelp: Fix URLs for project_files in Windows --- sphinx/builders/qthelp.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 44b968111..9afe47637 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -269,7 +269,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): resourcedir = root.startswith((staticdir, imagesdir)) for fn in sorted(files): if (resourcedir and not fn.endswith('.js')) or fn.endswith('.html'): - filename = path.join(root, fn)[olen:] + filename = posixpath.join(root, fn)[olen:] project_files.append(filename) return project_files From d8f4e47fc8c0a6358c3451e1147d21aaca82cceb Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Wed, 2 May 2018 02:02:20 +0900 Subject: [PATCH 20/25] Fix broken testcase caused by path separator --- tests/test_ext_doctest.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/test_ext_doctest.py b/tests/test_ext_doctest.py index d19d5b4e5..4aad0d274 100644 --- a/tests/test_ext_doctest.py +++ b/tests/test_ext_doctest.py @@ -8,6 +8,7 @@ :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ +import os import pytest from packaging.specifiers import InvalidSpecifier from packaging.version import InvalidVersion @@ -68,7 +69,7 @@ def test_reporting_with_autodoc(app, status, warning, capfd): written = [] app.builder._warn_out = written.append app.builder.build_all() - lines = '\n'.join(written).split('\n') + lines = '\n'.join(written).replace(os.sep, '/').split('\n') failures = [l for l in lines if l.startswith('File')] expected = [ 'File "dir/inner.rst", line 1, in default', From fce6d0d7d7e8a53d2cfd78c9e82a0455f8d02da0 Mon Sep 17 00:00:00 2001 From: Takayuki SHIMIZUKAWA Date: Wed, 2 May 2018 10:55:11 +0900 Subject: [PATCH 21/25] add debug log for patching/extracting i18n nodes (#4918) After fixing #4919, sphinx/util/logging.py:L120 must be commented-in and next L121 line will be removed. --- sphinx/util/logging.py | 34 ++++++++++++++++++++++++++++++++-- sphinx/util/nodes.py | 24 ++++++++++++++++++++++-- 2 files changed, 54 insertions(+), 4 deletions(-) diff --git a/sphinx/util/logging.py b/sphinx/util/logging.py index 5034c007d..dcd715dd3 100644 --- a/sphinx/util/logging.py +++ b/sphinx/util/logging.py @@ -17,14 +17,14 @@ from contextlib import contextmanager from docutils import nodes from docutils.utils import get_source_line -from six import PY2, StringIO +from six import PY2, StringIO, text_type from sphinx.errors import SphinxWarning from sphinx.util.console import colorize if False: # For type annotation - from typing import Any, Dict, Generator, IO, List, Tuple, Union # NOQA + from typing import Any, Dict, Generator, IO, List, Tuple, Union, Optional # NOQA from docutils import nodes # NOQA from sphinx.application import Sphinx # NOQA @@ -94,6 +94,36 @@ def convert_serializable(records): r.location = get_node_location(location) # type: ignore +def get_full_module_name(node): + # type: (nodes.Node) -> str + """ + return full module dotted path like: 'docutils.nodes.paragraph' + + :param nodes.Node node: target node + :return: full module dotted path + """ + return '{}.{}'.format(node.__module__, node.__class__.__name__) + + +def repr_domxml(node, length=80): + # type: (nodes.Node, Optional[int]) -> unicode + """ + return DOM XML representation of the specified node like: + 'New in version...' + + :param nodes.Node node: target node + :param int length: + length of return value to be striped. if false-value is specified, repr_domxml + returns full of DOM XML representation. + :return: DOM XML representation + """ + # text = node.asdom().toxml() # #4919 crush if node has secnumber with tuple value + text = text_type(node) # workaround for #4919 + if length and len(text) > length: + text = text[:length] + '...' + return text + + class SphinxWarningLogRecord(logging.LogRecord): """Log record class supporting location""" location = None # type: Any diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py index bdda1369b..14a3c1bc0 100644 --- a/sphinx/util/nodes.py +++ b/sphinx/util/nodes.py @@ -21,7 +21,7 @@ from sphinx.util import logging if False: # For type annotation - from typing import Any, Callable, Iterable, List, Set, Tuple, Union # NOQA + from typing import Any, Callable, Iterable, List, Set, Tuple # NOQA from sphinx.builders import Builder # NOQA from sphinx.utils.tags import Tags # NOQA @@ -41,13 +41,19 @@ def apply_source_workaround(node): # * rawsource of term node will have: ``term text : classifier1 : classifier2`` # * rawsource of classifier node will be None if isinstance(node, nodes.classifier) and not node.rawsource: + logger.debug('[i18n] PATCH: %r to have source, line and rawsource: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) definition_list_item = node.parent node.source = definition_list_item.source node.line = definition_list_item.line - 1 node.rawsource = node.astext() # set 'classifier1' (or 'classifier2') if isinstance(node, nodes.image) and node.source is None: + logger.debug('[i18n] PATCH: %r to have source, line: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) node.source, node.line = node.parent.source, node.parent.line if isinstance(node, nodes.term): + logger.debug('[i18n] PATCH: %r to have rawsource: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) # strip classifier from rawsource of term for classifier in reversed(node.parent.traverse(nodes.classifier)): node.rawsource = re.sub(r'\s*:\s*%s' % re.escape(classifier.astext()), @@ -67,6 +73,8 @@ def apply_source_workaround(node): nodes.image, # #3093 image directive in substitution nodes.field_name, # #3335 field list syntax ))): + logger.debug('[i18n] PATCH: %r to have source and line: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) node.source = find_source_node(node) node.line = 0 # need fix docutils to get `node.line` return @@ -74,7 +82,6 @@ def apply_source_workaround(node): IGNORED_NODES = ( nodes.Invisible, - nodes.Inline, nodes.literal_block, nodes.doctest_block, addnodes.versionmodified, @@ -96,17 +103,30 @@ def is_translatable(node): if isinstance(node, addnodes.translatable): return True + if isinstance(node, nodes.Inline) and 'translatable' not in node: + # inline node must not be translated if 'translatable' is not set + return False + if isinstance(node, nodes.TextElement): if not node.source: + logger.debug('[i18n] SKIP %r because no node.source: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) return False # built-in message if isinstance(node, IGNORED_NODES) and 'translatable' not in node: + logger.debug("[i18n] SKIP %r because node is in IGNORED_NODES " + "and no node['translatable']: %s", + logging.get_full_module_name(node), logging.repr_domxml(node)) return False if not node.get('translatable', True): # not(node['translatable'] == True or node['translatable'] is None) + logger.debug("[i18n] SKIP %r because not node['translatable']: %s", + logging.get_full_module_name(node), logging.repr_domxml(node)) return False # orphan # XXX ignore all metadata (== docinfo) if isinstance(node, nodes.field_name) and node.children[0] == 'orphan': + logger.debug('[i18n] SKIP %r because orphan node: %s', + logging.get_full_module_name(node), logging.repr_domxml(node)) return False return True From d55b17d091b6b3dc6bde1cf5dfb6817862148594 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 3 May 2018 09:34:02 +0900 Subject: [PATCH 22/25] Update CHANGES for PR #4924 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 43c14e5b4..2da6c384b 100644 --- a/CHANGES +++ b/CHANGES @@ -16,6 +16,8 @@ Features added Bugs fixed ---------- +* #4924: html search: Upper characters problem in any other languages + Testing -------- From 656f80cca9c9db246754ccec385cb7584efe42ae Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 3 May 2018 10:23:34 +0900 Subject: [PATCH 23/25] mypy: add --no-strict-optional Since mypy-0.600, validations for Optional becomes very strict. It interfere our development. So this disables it temporarily. --- setup.cfg | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.cfg b/setup.cfg index ac4dafdbc..091b59bbd 100644 --- a/setup.cfg +++ b/setup.cfg @@ -51,6 +51,7 @@ follow_imports = skip incremental = True check_untyped_defs = True warn_unused_ignores = True +strict_optional = False [tool:pytest] filterwarnings = From b1d79a417524755dae1618b317f96459548f23f8 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 3 May 2018 10:31:18 +0900 Subject: [PATCH 24/25] Fix mypy violations --- sphinx/ext/inheritance_diagram.py | 2 +- sphinx/setup_command.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py index 6f8256662..14593ac99 100644 --- a/sphinx/ext/inheritance_diagram.py +++ b/sphinx/ext/inheritance_diagram.py @@ -239,7 +239,7 @@ class InheritanceGraph(object): def get_all_class_names(self): # type: () -> List[unicode] """Get all of the class names involved in the graph.""" - return [fullname for (_, fullname, _, _) in self.class_info] # type: ignore + return [fullname for (_, fullname, _, _) in self.class_info] # These are the default attrs for graphviz default_graph_attrs = { diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index 1f160fec1..ddb2f1105 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -16,7 +16,7 @@ from __future__ import print_function import os import sys from distutils.cmd import Command -from distutils.errors import DistutilsOptionError, DistutilsExecError # type: ignore +from distutils.errors import DistutilsOptionError, DistutilsExecError from six import StringIO, string_types From cbf4ee24f9c7f83a7558786d2f43c9b79ad60418 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Fri, 27 Apr 2018 22:23:59 +0900 Subject: [PATCH 25/25] Fix #4811: The files under html_static_path are excluded from source --- CHANGES | 2 ++ doc/usage/configuration.rst | 11 +++++++++-- sphinx/builders/html.py | 2 +- tests/roots/test-html_assets/extra/index.rst | 0 tests/roots/test-html_assets/static/index.rst | 0 tests/test_build_html.py | 4 ++++ 6 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 tests/roots/test-html_assets/extra/index.rst create mode 100644 tests/roots/test-html_assets/static/index.rst diff --git a/CHANGES b/CHANGES index 1f412d1cf..aaf0fd38a 100644 --- a/CHANGES +++ b/CHANGES @@ -26,6 +26,8 @@ Incompatible changes * ``docutils.conf`` on ``$HOME`` and ``/etc`` directories are ignored. Only ``docutils.conf`` on confdir is refered. * #789: ``:samp:`` role supports to escape curly braces with backslash +* #4811: The files under :confval:`html_static_path` are excluded from source + files. Deprecated ---------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 948a9ffbc..0c3353f98 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -883,6 +883,9 @@ that use Sphinx's HTMLWriter class. named :file:`default.css` will overwrite the theme's :file:`default.css`. + As these files are not meant to be built, they are automatically excluded + from source files. + .. note:: For security reason, dotfiles under ``html_static_path`` will @@ -901,6 +904,10 @@ that use Sphinx's HTMLWriter class. .. versionchanged:: 1.0 The entries in :confval:`html_static_path` can now be single files. + .. versionchanged:: 1.8 + The files under :confval:`html_static_path` are excluded from source + files. + .. confval:: html_extra_path A list of paths that contain extra files not directly related to @@ -909,8 +916,8 @@ that use Sphinx's HTMLWriter class. directory. They are copied to the output directory. They will overwrite any existing file of the same name. - As these files are not meant to be built, they are automatically added to - :confval:`exclude_patterns`. + As these files are not meant to be built, they are automatically excluded + from source files. .. versionadded:: 1.2 diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 7e6475980..2c8ac42ea 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -411,7 +411,7 @@ class StandaloneHTMLBuilder(Builder): def get_asset_paths(self): # type: () -> List[unicode] - return self.config.html_extra_path + return self.config.html_extra_path + self.config.html_static_path def render_partial(self, node): # type: (nodes.Nodes) -> Dict[unicode, unicode] diff --git a/tests/roots/test-html_assets/extra/index.rst b/tests/roots/test-html_assets/extra/index.rst new file mode 100644 index 000000000..e69de29bb diff --git a/tests/roots/test-html_assets/static/index.rst b/tests/roots/test-html_assets/static/index.rst new file mode 100644 index 000000000..e69de29bb diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 655feec03..2b45720d1 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -1089,6 +1089,10 @@ def test_enumerable_node(app, cached_etree_parse, fname, expect): def test_html_assets(app): app.builder.build_all() + # exclude_path and its family + assert not (app.outdir / 'static' / 'index.html').exists() + assert not (app.outdir / 'extra' / 'index.html').exists() + # html_static_path assert not (app.outdir / '_static' / '.htaccess').exists() assert not (app.outdir / '_static' / '.htpasswd').exists()