Merge branch '1.7'

CHANGES

@@ -75,6 +75,9 @@ Bugs fixed
 * #4615: The argument of ``sphinx.build`` has been changed in 1.7.0
 * autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
   been changed
+* #4630: Have order on msgids in sphinx.pot deterministic
+* #4563: autosummary: Incorrect end of line punctuation detection
+* #4577: Enumerated sublists with explicit start with wrong number
 
 Testing
 --------

sphinx/builders/gettext.py

@@ -12,7 +12,7 @@
 from __future__ import unicode_literals
 
 from codecs import open
-from collections import defaultdict
+from collections import defaultdict, OrderedDict
 from datetime import datetime, tzinfo, timedelta
 from os import path, walk, getenv
 from time import time
@@ -68,7 +68,7 @@ class Catalog(object):
         # type: () -> None
         self.messages = []  # type: List[unicode]
                             # retain insertion order, a la OrderedDict
-        self.metadata = {}  # type: Dict[unicode, List[Tuple[unicode, int, unicode]]]
+        self.metadata = OrderedDict()  # type: Dict[unicode, List[Tuple[unicode, int, unicode]]]  # NOQA
                                         # msgid -> file, line, uid
 
     def add(self, msg, origin):
@@ -237,7 +237,8 @@ class MessageCatalogBuilder(I18nBuilder):
 
     def _extract_from_template(self):
         # type: () -> None
-        files = self._collect_templates()
+        files = list(self._collect_templates())
+        files.sort()
         logger.info(bold('building [%s]: ' % self.name), nonl=1)
         logger.info('targets for %d template files', len(files))
 

sphinx/ext/autosummary/__init__.py

@@ -64,6 +64,7 @@ from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
+from docutils.parsers.rst.states import RSTStateMachine, state_classes
 from docutils.statemachine import ViewList
 from six import string_types
 from six import text_type
@@ -77,6 +78,7 @@ from sphinx.ext.autodoc.directive import DocumenterBridge, Options
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import import_object, rst, logging
+from sphinx.util.docutils import new_document
 
 if TYPE_CHECKING:
     from typing import Any, Dict, List, Tuple, Type, Union  # NOQA
@@ -342,27 +344,7 @@ class Autosummary(Directive):
             # -- Grab the summary
 
             documenter.add_content(None)
-            doc = self.result.data
+            summary = extract_summary(self.result.data[:], self.state.document)
-
-            while doc and not doc[0].strip():
-                doc.pop(0)
-
-            # If there's a blank line, then we can assume the first sentence /
-            # paragraph has ended, so anything after shouldn't be part of the
-            # summary
-            for i, piece in enumerate(doc):
-                if not piece.strip():
-                    doc = doc[:i]
-                    break
-
-            # Try to find the "first sentence", which may span multiple lines
-            m = re.search(r"^([A-Z].*?\.)(?:\s|$)", " ".join(doc).strip())
-            if m:
-                summary = m.group(1).strip()
-            elif doc:
-                summary = doc[0].strip()
-            else:
-                summary = ''
 
             items.append((display_name, sig, summary, real_name))
 
@@ -469,6 +451,40 @@ def mangle_signature(sig, max_chars=30):
     return u"(%s)" % sig
 
 
+def extract_summary(doc, document):
+    # type: (List[unicode], Any) -> unicode
+    """Extract summary from docstring."""
+
+    # Skip a blank lines at the top
+    while doc and not doc[0].strip():
+        doc.pop(0)
+
+    # If there's a blank line, then we can assume the first sentence /
+    # paragraph has ended, so anything after shouldn't be part of the
+    # summary
+    for i, piece in enumerate(doc):
+        if not piece.strip():
+            doc = doc[:i]
+            break
+
+    # Try to find the "first sentence", which may span multiple lines
+    sentences = " ".join(doc).split('.')
+    if len(sentences) == 1:
+        summary = sentences[0].strip()
+    else:
+        summary = ''
+        state_machine = RSTStateMachine(state_classes, 'Body')
+        while sentences:
+            summary += sentences.pop(0) + '.'
+            node = new_document('', document.settings)
+            state_machine.run([summary], node)
+            if not node.traverse(nodes.system_message):
+                # considered as that splitting by period does not break inline markups
+                break
+
+    return summary
+
+
 def limited_join(sep, items, max_chars=30, overflow_marker="..."):
     # type: (unicode, List[unicode], int, unicode) -> unicode
     """Join a number of strings to one, limiting the length to *max_chars*.

sphinx/writers/latex.py

@@ -1581,9 +1581,19 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_enumerated_list(self, node):
         # type: (nodes.Node) -> None
+        def get_nested_level(node):
+            # type: (nodes.Node) -> int
+            if node is None:
+                return 0
+            elif isinstance(node, nodes.enumerated_list):
+                return get_nested_level(node.parent) + 1
+            else:
+                return get_nested_level(node.parent)
+
         self.body.append('\\begin{enumerate}\n')
         if 'start' in node:
-            self.body.append('\\setcounter{enumi}{%d}\n' % (node['start'] - 1))
+            nested = get_nested_level(node)
+            self.body.append('\\setcounter{enum%s}{%d}\n' % ('i' * nested, node['start'] - 1))
         if self.table:
             self.table.has_problematic = True
 

tests/conftest.py

@@ -10,9 +10,9 @@
 import os
 import shutil
 import sys
-import warnings
 
 import pytest
+
 from sphinx.testing.path import path
 
 pytest_plugins = 'sphinx.testing.fixtures'

tests/py35/test_autodoc_py35.py

@@ -11,16 +11,15 @@
 """
 
 # "raises" imported for usage by autodoc
-import six
 import sys
-from sphinx.testing.util import SphinxTestApp, Struct
+
 import pytest
-
+import six
-from six import StringIO
 from docutils.statemachine import ViewList
+from six import StringIO
 
-from sphinx.ext.autodoc import AutoDirective, add_documenter, \
+from sphinx.ext.autodoc import add_documenter, FunctionDocumenter, ALL  # NOQA
-    ModuleLevelDocumenter, FunctionDocumenter, cut_lines, between, ALL
+from sphinx.testing.util import SphinxTestApp, Struct
 from sphinx.util import logging
 
 app = None
@@ -279,8 +278,8 @@ class Base(object):
     def inheritedmeth(self):
         """Inherited function."""
 
-if six.PY3 and sys.version_info[:2] >= (3, 5):
 
+if six.PY3 and sys.version_info[:2] >= (3, 5):
     async def _other_coro_func():
         return "run"
 
@@ -345,5 +344,4 @@ class Class(Base):
 
         async def do_coroutine(self):
             """A documented coroutine function"""
-
+            attr_coro_result = await _other_coro_func()  # NOQA
-            attr_coro_result = await _other_coro_func()

tests/roots/test-add_enumerable_node/enumerable_node.py

@@ -2,7 +2,6 @@
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
-from sphinx.util.nodes import split_explicit_title
 
 
 class my_figure(nodes.figure):

tests/roots/test-add_source_parser-conflicts-with-users-setting/conf.py

@@ -2,6 +2,7 @@
 
 import os
 import sys
+
 from docutils.parsers import Parser
 
 sys.path.insert(0, os.path.abspath('.'))

tests/roots/test-add_source_parser/conf.py

@@ -2,6 +2,7 @@
 
 import os
 import sys
+
 from docutils.parsers import Parser
 
 sys.path.insert(0, os.path.abspath('.'))

tests/roots/test-api-set-translator/conf.py

@@ -1,16 +1,17 @@
 # -*- coding: utf-8 -*-
-## set this by test
+# set this by test
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from docutils.writers.docutils_xml import XMLTranslator
+
 from sphinx.writers.html import HTMLTranslator
 from sphinx.writers.latex import LaTeXTranslator
 from sphinx.writers.manpage import ManualPageTranslator
 from sphinx.writers.texinfo import TexinfoTranslator
 from sphinx.writers.text import TextTranslator
 from sphinx.writers.websupport import WebSupportTranslator
-from docutils.writers.docutils_xml import XMLTranslator
 
 
 project = 'test'

tests/roots/test-api-set-translator/translator.py

@@ -2,5 +2,6 @@
 
 from sphinx.writers.html import HTMLTranslator
 
+
 class ExtHTMLTranslator(HTMLTranslator):
     pass

tests/roots/test-apidoc-toc/mypackage/main.py

@@ -2,7 +2,6 @@
 import os
 
 import mod_resource
-
 import mod_something
 
 

tests/roots/test-apidoc-trailing-underscore/package_/module_.py

@@ -1,7 +1,9 @@
 """ A module with a trailing underscore """
 
+
 class SomeClass_:
     """ A class with a trailing underscore """
 
+
 def some_function_(some_arg_):
     """ A function with a trailing underscore in name and argument """

tests/roots/test-autosummary/conf.py

@@ -1,4 +1,5 @@
-import sys, os
+import os
+import sys
 
 sys.path.insert(0, os.path.abspath('.'))
 

tests/roots/test-autosummary/dummy_module.py

@@ -8,6 +8,7 @@
    C.C2
 """
 
+
 def withSentence():
     '''I have a sentence which
     spans multiple lines. Then I have
@@ -15,6 +16,7 @@ def withSentence():
     '''
     pass
 
+
 def noSentence():
     '''this doesn't start with a
     capital. so it's not considered
@@ -22,6 +24,7 @@ def noSentence():
     '''
     pass
 
+
 def emptyLine():
     '''This is the real summary
 

tests/roots/test-autosummary/underscore_module_.py

@@ -1,12 +1,15 @@
 """
 module with trailing underscores everywhere
 """
+
+
 class class_(object):
     """ Class """
     def method_(_arg):
         """ Method """
         pass
 
+
 def function_(_arg):
     """ Function """
     pass

tests/roots/test-config/conf.py

@@ -8,13 +8,19 @@ value5 = 3  # parent type
 value6 = ()  # other sequence type, also raises
 value7 = ['foo']  # explicitly permitted
 
+
 class A(object):
     pass
+
+
 class B(A):
     pass
+
+
 class C(A):
     pass
 
+
 value8 = C()  # sibling type
 
 # both have no default or permissible types

tests/roots/test-correct-year/conf.py

@@ -1,3 +1,2 @@
 
 copyright = u'2006-2009, Author'
-

tests/roots/test-directive-code/conf.py

@@ -3,4 +3,3 @@
 master_doc = 'index'
 exclude_patterns = ['_build']
 numfig = True
-

tests/roots/test-double-inheriting-theme/conf.py

@@ -1,7 +1,5 @@
 # -*- coding: utf-8 -*-
 
-import sys, os
-
 templates_path = ['_templates']
 master_doc = 'index'
 html_theme = 'base_theme2'

tests/roots/test-ext-autodoc/autodoc_dummy_bar.py

@@ -1,5 +1,6 @@
 from bug2437.autodoc_dummy_foo import Foo
 
+
 class Bar(object):
     """Dummy class Bar with alias."""
     my_name = Foo

tests/roots/test-ext-autodoc/autodoc_dummy_module.py

@@ -1,6 +1,6 @@
-from dummy import *
+from dummy import *   # NOQA
 
 
 def test():
     """Dummy function using dummy.*"""
-    dummy_function()
+    dummy_function()   # NOQA

tests/roots/test-ext-autodoc/conf.py

@@ -1,4 +1,5 @@
-import sys, os
+import os
+import sys
 
 sys.path.insert(0, os.path.abspath('.'))
 

tests/roots/test-ext-autodoc/target/__init__.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 
 import enum
+
 from six import StringIO, add_metaclass
+
 from sphinx.ext.autodoc import add_documenter  # NOQA
 
 

tests/roots/test-ext-autosummary/autosummary_dummy_module.py

@@ -1,4 +1,4 @@
-from os import *
+from os import *  # NOQA
 
 
 class Foo:

tests/roots/test-ext-autosummary/conf.py

@@ -1,4 +1,5 @@
-import sys, os
+import os
+import sys
 
 sys.path.insert(0, os.path.abspath('.'))
 

tests/roots/test-ext-doctest-with-autodoc/conf.py

@@ -1,5 +1,5 @@
-from os import path
 import sys
+from os import path
 
 sys.path.insert(0, path.abspath(path.dirname(__file__)))
 

tests/roots/test-ext-ifconfig/conf.py

@@ -6,6 +6,7 @@ exclude_patterns = ['_build']
 
 confval1 = True
 
+
 def setup(app):
     app.add_config_value('confval1', False, None)
     app.add_config_value('confval2', False, None)

tests/roots/test-ext-viewcode/conf.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
-import sys
 import os
+import sys
 
 sys.path.insert(0, os.path.abspath('.'))
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
@@ -9,7 +9,7 @@ master_doc = 'index'
 exclude_patterns = ['_build']
 
 
-if 'test_linkcode' in tags:
+if 'test_linkcode' in tags:  # NOQA
     extensions.remove('sphinx.ext.viewcode')
     extensions.append('sphinx.ext.linkcode')
 

tests/roots/test-ext-viewcode/spam/__init__.py

@@ -1,7 +1,4 @@
 from __future__ import absolute_import
 
-from .mod1 import func1, Class1
+from .mod1 import func1, Class1  # NOQA
-from .mod2 import (
+from .mod2 import func2, Class2  # NOQA
-    func2,
-    Class2,
-)

tests/roots/test-ext-viewcode/spam/mod1.py

@@ -2,9 +2,11 @@
 mod1
 """
 
+
 def decorator(f):
     return f
 
+
 @decorator
 def func1(a, b):
     """
@@ -19,6 +21,7 @@ class Class1(object):
     this is Class1
     """
 
+
 class Class3(object):
     """
     this is Class3

tests/roots/test-ext-viewcode/spam/mod2.py

@@ -2,9 +2,11 @@
 mod2
 """
 
+
 def decorator(f):
     return f
 
+
 @decorator
 def func2(a, b):
     """

tests/roots/test-gettext-template/_templates/template1.html

@@ -0,0 +1,5 @@
+{% extends "layout.html" %}
+{% block body %}
+  <h1>{{ _('Template 1') }}</h1>
+  <p>{%trans%}This is Template 1.{%endtrans%}</p>
+{% endblock %}

tests/roots/test-gettext-template/_templates/template2.html

@@ -0,0 +1,5 @@
+{% extends "layout.html" %}
+{% block body %}
+  <h1>{{ _('Template 2') }}</h1>
+  <p>{%trans%}This is Template 2.{%endtrans%}</p>
+{% endblock %}

tests/roots/test-gettext-template/conf.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+templates_path = ['_templates']

tests/roots/test-image-in-parsed-literal/conf.py

@@ -10,4 +10,3 @@ rst_epilog = '''
     :align: middle
     :alt: alternative_text
 '''
-

tests/roots/test-image-in-section/conf.py

@@ -9,4 +9,3 @@ rst_epilog = '''
     :height: 15pt
     :alt: alternative_text
 '''
-

tests/roots/test-inheritance/conf.py

@@ -1,4 +1,5 @@
-import sys, os
+import os
+import sys
 
 sys.path.insert(0, os.path.abspath('.'))
 

tests/roots/test-inheritance/dummy/test.py

@@ -10,21 +10,26 @@
 
 """
 
+
 class A(object):
     pass
 
+
 class B(A):
     pass
 
+
 class C(A):
     pass
 
+
 class D(B, C):
     pass
 
+
 class E(B):
     pass
 
+
 class F(C):
     pass
-

tests/roots/test-nested-enumerated-list/conf.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+
+latex_documents = [
+    (master_doc, 'test.tex', 'The basic Sphinx documentation for testing', 'Sphinx', 'report')
+]

tests/roots/test-nested-enumerated-list/index.rst

@@ -0,0 +1,15 @@
+nested-enumerated-list
+======================
+
+5. Sphinx
+
+   d. Documentation builder
+   e. Egypt
+
+      10) Pyramid
+      11) Nile River
+
+6. Markup
+
+   iii. reStructuredText
+   iv. Markdown

tests/roots/test-root/autodoc_missing_imports.py

@@ -1,17 +1,20 @@
 
-import missing_module
+import missing_module   # NOQA
-from missing_module import missing_name
+import missing_package1.missing_module1   # NOQA
-import missing_package1.missing_module1
+from missing_module import missing_name   # NOQA
-from missing_package2 import missing_module2
+from missing_package2 import missing_module2   # NOQA
-from missing_package3.missing_module3 import missing_name
+from missing_package3.missing_module3 import missing_name   # NOQA
-import sphinx.missing_module4
+
-from sphinx.missing_module4 import missing_name2
+import sphinx.missing_module4   # NOQA
+from sphinx.missing_module4 import missing_name2   # NOQA
+
 
 @missing_name
 def decoratedFunction():
     """decoratedFunction docstring"""
     return None
 
+
 class TestAutodoc(object):
     """TestAutodoc docstring."""
     @missing_name
@@ -19,4 +22,5 @@ class TestAutodoc(object):
         """TestAutodoc::decoratedMethod docstring"""
         return None
 
+
 sphinx.missing_module4.missing_function(len(missing_name2))

tests/roots/test-root/autodoc_target.py

@@ -1,7 +1,9 @@
 # -*- coding: utf-8 -*-
 
 import enum
+
 from six import StringIO, add_metaclass
+
 from sphinx.ext.autodoc import add_documenter  # NOQA
 
 

tests/roots/test-root/conf.py

@@ -1,6 +1,13 @@
 # -*- coding: utf-8 -*-
 
-import sys, os
+import os
+import sys
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx import addnodes
+
 
 sys.path.append(os.path.abspath('.'))
 
@@ -75,15 +82,10 @@ autodoc_mock_imports = [
 ]
 
 # modify tags from conf.py
-tags.add('confpytag')
+tags.add('confpytag')  # NOQA
+
 
 # -- extension API
-
-from docutils import nodes
-from docutils.parsers.rst import Directive
-from sphinx import addnodes
-
-
 def userdesc_parse(env, sig, signode):
     x, y = sig.split(':')
     signode += addnodes.desc_name(x, x)

tests/roots/test-root/ext.py

@@ -1,4 +1,5 @@
 # Test extension module
 
+
 def setup(app):
     app.add_config_value('value_from_ext', [], False)

tests/roots/test-root/parsermod.py

@@ -1,5 +1,5 @@
-from docutils.parsers import Parser
 from docutils import nodes
+from docutils.parsers import Parser
 
 
 class Parser(Parser):

tests/roots/test-setup/setup.py

@@ -1,4 +1,5 @@
 from distutils.core import setup
+
 from sphinx.setup_command import BuildDoc
 
 cmdclass = {'build_sphinx': BuildDoc}

tests/roots/test-stylesheets/conf.py

@@ -4,9 +4,9 @@ master_doc = 'index'
 html_theme = 'classic'
 templates_path = ['_templates']
 
+
 def setup(app):
     app.add_stylesheet('persistent.css')
     app.add_stylesheet('default.css', title="Default")
     app.add_stylesheet('alternate1.css', title="Alternate", alternate=True)
     app.add_stylesheet('alternate2.css', alternate=True)
-

tests/roots/test-templating/conf.py

@@ -9,4 +9,3 @@ exclude_patterns = ['_build']
 
 extensions = ['sphinx.ext.autosummary']
 autosummary_generate = ['autosummary_templating']
-

tests/roots/test-theming/conf.py

@@ -4,4 +4,3 @@ html_theme = 'test-theme'
 html_theme_path = ['.', 'test_theme']
 master_doc = 'index'
 exclude_patterns = ['_build']
-

tests/roots/test-theming/setup.py

@@ -12,5 +12,3 @@ setup(
        path = test_theme:get_path
     """,
 )
-
-

tests/roots/test-theming/test_theme/__init__.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import os
 
+
 def get_path():
     return os.path.dirname(os.path.abspath(__file__))

tests/test_application.py

@@ -8,14 +8,13 @@
     :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+import pytest
 from docutils import nodes
 
 from sphinx.application import ExtensionError
 from sphinx.domains import Domain
-from sphinx.util import logging
-
 from sphinx.testing.util import strip_escseq
-import pytest
+from sphinx.util import logging
 
 
 def test_events(app, status, warning):

tests/test_autodoc.py

@@ -11,15 +11,14 @@
 """
 
 import sys
-from six import PY3
 
-from sphinx.testing.util import SphinxTestApp, Struct  # NOQA
 import pytest
-
 from docutils.statemachine import ViewList
+from six import PY3
 
 from sphinx.ext.autodoc import AutoDirective, add_documenter, \
     ModuleLevelDocumenter, FunctionDocumenter, cut_lines, between, ALL
+from sphinx.testing.util import SphinxTestApp, Struct  # NOQA
 from sphinx.util import logging
 
 app = None

tests/test_build.py

@@ -10,13 +10,14 @@
 """
 
 import pickle
-from docutils import nodes
+import sys
+from textwrap import dedent
+
 import mock
 import pytest
-from textwrap import dedent
+from docutils import nodes
-from sphinx.errors import SphinxError
-import sys
 
+from sphinx.errors import SphinxError
 from sphinx.testing.path import path
 
 
@@ -60,13 +61,13 @@ def nonascii_srcdir(request, rootdir, sphinx_test_tempdir):
 
 
 # note: this test skips building docs for some builders because they have independent testcase.
-#       (html, latex, texinfo and manpage)
+#       (html, epub, latex, texinfo and manpage)
 @pytest.mark.parametrize(
     "buildername",
     [
         # note: no 'html' - if it's ok with dirhtml it's ok with html
         'dirhtml', 'singlehtml', 'pickle', 'json', 'text', 'htmlhelp', 'qthelp',
-        'epub', 'applehelp', 'changes', 'xml', 'pseudoxml', 'linkcheck',
+        'applehelp', 'changes', 'xml', 'pseudoxml', 'linkcheck',
     ],
 )
 @mock.patch('sphinx.builders.linkcheck.requests.head',

tests/test_build_applehelp.py

@@ -14,6 +14,7 @@
 import plistlib
 
 import pytest
+
 from sphinx.testing.path import path
 
 # Use plistlib.load in 3.4 and above

tests/test_build_epub.py

@@ -9,11 +9,25 @@
     :license: BSD, see LICENSE for details.
 """
 
+import os
+from subprocess import Popen, PIPE
 from xml.etree import ElementTree
 
 import pytest
 
 
+# check given command is runnable
+def runnable(command):
+    try:
+        p = Popen(command, stdout=PIPE)
+    except OSError:
+        # command not found
+        return False
+    else:
+        p.communicate()
+        return p.returncode
+
+
 class EPUBElementTree(object):
     """Test helper for content.opf and tox.ncx"""
     namespaces = {
@@ -245,3 +259,18 @@ def test_epub_writing_mode(app):
     # vertical / writing-mode (CSS)
     css = (app.outdir / '_static' / 'epub.css').text()
     assert 'writing-mode: vertical-rl;' in css
+
+
+@pytest.mark.sphinx('epub')
+def test_run_epubcheck(app):
+    app.build()
+
+    epubcheck = os.environ.get('EPUBCHECK_PATH', '/usr/share/java/epubcheck.jar')
+    if runnable('java') and os.path.exists(epubcheck):
+        p = Popen(['java', '-jar', epubcheck, app.outdir / 'Sphinx.epub'],
+                  stdout=PIPE, stderr=PIPE)
+        stdout, stderr = p.communicate()
+        if p.returncode != 0:
+            print(stdout)
+            print(stderr)
+            assert False, 'epubcheck exited with return code %s' % p.returncode

tests/test_build_gettext.py

@@ -10,9 +10,9 @@
 """
 from __future__ import print_function
 
+import gettext
 import os
 import re
-import gettext
 from subprocess import Popen, PIPE
 
 import pytest
@@ -165,3 +165,18 @@ def test_gettext_template(app):
     result = (app.outdir / 'sphinx.pot').text(encoding='utf-8')
     assert "Welcome" in result
     assert "Sphinx %(version)s" in result
+
+
+@pytest.mark.sphinx('gettext', testroot='gettext-template')
+def test_gettext_template_msgid_order_in_sphinxpot(app):
+    app.builder.build_all()
+    assert (app.outdir / 'sphinx.pot').isfile()
+
+    result = (app.outdir / 'sphinx.pot').text(encoding='utf-8')
+    assert re.search(
+        ('msgid "Template 1".*'
+         'msgid "This is Template 1\.".*'
+         'msgid "Template 2".*'
+         'msgid "This is Template 2\.".*'),
+        result,
+        flags=re.S)

tests/test_build_html.py

@@ -11,15 +11,15 @@
 
 import os
 import re
+import xml.etree.cElementTree as ElementTree
 from itertools import cycle, chain
 
+import pytest
+from html5lib import getTreeBuilder, HTMLParser
 from six import PY3
 
-from sphinx.util.inventory import InventoryFile
 from sphinx.testing.util import remove_unicode_literals, strip_escseq
-import xml.etree.cElementTree as ElementTree
+from sphinx.util.inventory import InventoryFile
-from html5lib import getTreeBuilder, HTMLParser
-import pytest
 
 
 TREE_BUILDER = getTreeBuilder('etree', implementation=ElementTree)
@@ -1250,6 +1250,7 @@ def test_html_sidebar(app, status, warning):
     'index.html': [(".//em/a[@href='https://example.com/man.1']", "", True),
                    (".//em/a[@href='https://example.com/ls.1']", "", True),
                    (".//em/a[@href='https://example.com/sphinx.']", "", True)]
+
 }))
 @pytest.mark.sphinx('html', testroot='manpage_url', confoverrides={
     'manpages_url': 'https://example.com/{page}.{section}'})

tests/test_build_html5.py

@@ -18,11 +18,10 @@ import xml.etree.cElementTree as ElementTree
 
 import pytest
 from html5lib import getTreeBuilder, HTMLParser
+from test_build_html import flat_dict, tail_check, check_xpath
 
 from sphinx.util.docutils import is_html5_writer_available
 
-from test_build_html import flat_dict, tail_check, check_xpath
-
 TREE_BUILDER = getTreeBuilder('etree', implementation=ElementTree)
 HTML_PARSER = HTMLParser(TREE_BUILDER, namespaceHTMLElements=False)
 

tests/test_build_latex.py

@@ -13,19 +13,18 @@ from __future__ import print_function
 import os
 import re
 from itertools import product
-from subprocess import Popen, PIPE
 from shutil import copyfile
+from subprocess import Popen, PIPE
 
-from six import PY3
 import pytest
+from six import PY3
+from test_build_html import ENV_WARNINGS
 
 from sphinx.errors import SphinxError
-from sphinx.util.osutil import cd, ensuredir
-from sphinx.util import docutils
-from sphinx.writers.latex import LaTeXTranslator
-
 from sphinx.testing.util import remove_unicode_literals, strip_escseq
-from test_build_html import ENV_WARNINGS
+from sphinx.util import docutils
+from sphinx.util.osutil import cd, ensuredir
+from sphinx.writers.latex import LaTeXTranslator
 
 
 LATEX_ENGINES = ['pdflatex', 'lualatex', 'xelatex']
@@ -1143,3 +1142,14 @@ def test_latex_image_in_parsed_literal(app, status, warning):
     assert ('{\\sphinxunactivateextrasandspace \\raisebox{-0.5\\height}'
             '{\\scalebox{2.000000}{\\sphinxincludegraphics[height=1cm]{{pic}.png}}}'
             '}AFTER') in result
+
+
+@pytest.mark.sphinx('latex', testroot='nested-enumerated-list')
+def test_latex_nested_enumerated_list(app, status, warning):
+    app.builder.build_all()
+
+    result = (app.outdir / 'test.tex').text(encoding='utf8')
+    assert r'\setcounter{enumi}{4}' in result
+    assert r'\setcounter{enumii}{3}' in result
+    assert r'\setcounter{enumiii}{9}' in result
+    assert r'\setcounter{enumii}{2}' in result

tests/test_build_texinfo.py

@@ -14,13 +14,12 @@ import os
 import re
 from subprocess import Popen, PIPE
 
-from six import PY3
 import pytest
-
+from six import PY3
-from sphinx.writers.texinfo import TexinfoTranslator
+from test_build_html import ENV_WARNINGS
 
 from sphinx.testing.util import remove_unicode_literals, strip_escseq
-from test_build_html import ENV_WARNINGS
+from sphinx.writers.texinfo import TexinfoTranslator
 
 
 TEXINFO_WARNINGS = ENV_WARNINGS + """\

tests/test_build_text.py

@@ -8,9 +8,10 @@
     :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
-import pytest
 
+import pytest
 from docutils.utils import column_width
+
 from sphinx.writers.text import MAXWIDTH
 
 

tests/test_config.py

@@ -9,9 +9,9 @@
     :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
-from six import PY3, iteritems
-import pytest
 import mock
+import pytest
+from six import PY3, iteritems
 
 import sphinx
 from sphinx.config import Config

tests/test_directive_code.py

@@ -9,9 +9,10 @@
     :license: BSD, see LICENSE for details.
 """
 
-import pytest
 import os
 
+import pytest
+
 from sphinx.config import Config
 from sphinx.directives.code import LiteralIncludeReader
 from sphinx.testing.util import etree_parse

tests/test_directive_only.py

@@ -11,8 +11,8 @@
 
 import re
 
-from docutils import nodes
 import pytest
+from docutils import nodes
 
 
 @pytest.mark.sphinx('text', testroot='directive-only')

tests/test_docutilsconf.py

@@ -13,6 +13,7 @@ import re
 import sys
 
 import pytest
+
 from sphinx.testing.path import path
 
 

tests/test_domain_cpp.py

@@ -11,13 +11,13 @@
 
 import re
 
-from six import text_type
 import pytest
+from six import text_type
 
+import sphinx.domains.cpp as cppDomain
 from sphinx import addnodes
 from sphinx.domains.cpp import DefinitionParser, DefinitionError, NoOldIdError
 from sphinx.domains.cpp import Symbol, _max_id, _id_prefix
-import sphinx.domains.cpp as cppDomain
 
 
 def parse(name, string):

tests/test_domain_js.py

@@ -10,12 +10,11 @@
 """
 
 import pytest
-from mock import Mock
 from docutils import nodes
+from mock import Mock
 
 from sphinx import addnodes
 from sphinx.domains.javascript import JavaScriptDomain
-
 from sphinx.testing.util import assert_node
 
 

tests/test_domain_py.py

@@ -10,13 +10,12 @@
 """
 
 import pytest
+from docutils import nodes
 from mock import Mock
 from six import text_type
-from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.domains.python import py_sig_re, _pseudo_parse_arglist, PythonDomain
-
 from sphinx.testing.util import assert_node
 
 

tests/test_domain_std.py

@@ -9,8 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
-from docutils import nodes
 import mock
+from docutils import nodes
 
 from sphinx.domains.std import StandardDomain
 

tests/test_environment.py

@@ -10,9 +10,9 @@
 """
 import pytest
 
-from sphinx.testing.util import SphinxTestApp, path
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.builders.latex import LaTeXBuilder
+from sphinx.testing.util import SphinxTestApp, path
 
 app = env = None
 

tests/test_environment_indexentries.py

@@ -10,11 +10,12 @@
 """
 
 from collections import namedtuple
-from sphinx import locale
-from sphinx.environment.adapters.indexentries import IndexEntries
 
 import mock
 
+from sphinx import locale
+from sphinx.environment.adapters.indexentries import IndexEntries
+
 Environment = namedtuple('Environment', 'indexentries')
 
 dummy_builder = mock.Mock()

tests/test_environment_toctree.py

@@ -9,14 +9,14 @@
     :license: BSD, see LICENSE for details.
 """
 
+import pytest
 from docutils import nodes
 from docutils.nodes import bullet_list, list_item, caption, comment, reference
+
 from sphinx import addnodes
 from sphinx.addnodes import compact_paragraph, only
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.environment.adapters.toctree import TocTree
-import pytest
-
 from sphinx.testing.util import assert_node
 
 

tests/test_ext_apidoc.py

@@ -16,7 +16,6 @@ from collections import namedtuple
 import pytest
 
 from sphinx.ext.apidoc import main as apidoc_main
-
 from sphinx.testing.util import remove_unicode_literals
 
 

tests/test_ext_autodoc.py

@@ -10,7 +10,9 @@
 """
 
 import pickle
+
 import pytest
+
 from sphinx import addnodes
 
 

tests/test_ext_autosummary.py

@@ -9,14 +9,12 @@
     :license: BSD, see LICENSE for details.
 """
 
+import pytest
 from six import iteritems, StringIO
 
-from sphinx.ext.autosummary import mangle_signature, import_by_name
+from sphinx.ext.autosummary import mangle_signature, import_by_name, extract_summary
-
 from sphinx.testing.util import etree_parse
 
-import pytest
-
 html_warnfile = StringIO()
 
 
@@ -57,6 +55,29 @@ def test_mangle_signature():
         assert res == outp, (u"'%s' -> '%s' != '%s'" % (inp, res, outp))
 
 
+def test_extract_summary():
+    from sphinx.util.docutils import new_document
+    from mock import Mock
+    settings = Mock(language_code='',
+                    id_prefix='',
+                    auto_id_prefix='',
+                    pep_reference=False,
+                    rfc_reference=False)
+    document = new_document('', settings)
+
+    # normal case
+    doc = ['',
+           'This is a first sentence. And second one.',
+           '',
+           'Second block is here']
+    assert extract_summary(doc, document) == 'This is a first sentence.'
+
+    # inliner case
+    doc = ['This sentence contains *emphasis text having dots.*,',
+           'it does not break sentence.']
+    assert extract_summary(doc, document) == ' '.join(doc)
+
+
 @pytest.mark.sphinx('dummy', **default_kw)
 def test_get_items_summary(make_app, app_params):
     import sphinx.ext.autosummary
@@ -95,7 +116,7 @@ def test_get_items_summary(make_app, app_params):
 
     expected_values = {
         'withSentence': 'I have a sentence which spans multiple lines.',
-        'noSentence': "this doesn't start with a",
+        'noSentence': "this doesn't start with a capital.",
         'emptyLine': "This is the real summary",
         'module_attr': 'This is a module attribute',
         'C.class_attr': 'This is a class attribute',

tests/test_ext_doctest.py

@@ -9,10 +9,11 @@
     :license: BSD, see LICENSE for details.
 """
 import pytest
-from six import PY2
-from sphinx.ext.doctest import is_allowed_version
-from packaging.version import InvalidVersion
 from packaging.specifiers import InvalidSpecifier
+from packaging.version import InvalidVersion
+from six import PY2
+
+from sphinx.ext.doctest import is_allowed_version
 
 cleanup_called = 0
 

tests/test_ext_imgconverter.py

@@ -9,9 +9,10 @@
     :license: BSD, see LICENSE for details.
 """
 
-import pytest
 import os
 
+import pytest
+
 
 @pytest.mark.sphinx('latex', testroot='ext-imgconverter')
 @pytest.mark.xfail(os.name != 'posix', reason="Not working on windows")

tests/test_ext_inheritance.py

@@ -10,7 +10,9 @@
 """
 
 import os
+
 import pytest
+
 from sphinx.ext.inheritance_diagram import InheritanceDiagram
 
 
@@ -52,8 +54,7 @@ def test_inheritance_diagram(app, status, warning):
             ('dummy.test.F', 'dummy.test.F', ['dummy.test.C'], None),
             ('dummy.test.C', 'dummy.test.C', ['dummy.test.A'], None),
             ('dummy.test.E', 'dummy.test.E', ['dummy.test.B'], None),
-                        ('dummy.test.D', 'dummy.test.D',
+            ('dummy.test.D', 'dummy.test.D', ['dummy.test.B', 'dummy.test.C'], None),
-                            ['dummy.test.B', 'dummy.test.C'], None),
             ('dummy.test.B', 'dummy.test.B', ['dummy.test.A'], None)
         ]
 
@@ -83,12 +84,10 @@ def test_inheritance_diagram(app, status, warning):
             ('dummy.test.F', 'dummy.test.F', ['dummy.test.C'], None),
             ('dummy.test.C', 'dummy.test.C', ['dummy.test.A'], None),
             ('dummy.test.E', 'dummy.test.E', ['dummy.test.B'], None),
-                        ('dummy.test.D', 'dummy.test.D',
+            ('dummy.test.D', 'dummy.test.D', ['dummy.test.B', 'dummy.test.C'], None),
-                            ['dummy.test.B', 'dummy.test.C'], None),
             ('dummy.test.B', 'dummy.test.B', [], None)
         ]
 
-
     # inheritance diagram with 2 top classes
     # :top-classes: dummy.test.B, dummy.test.C
     # Note: we're specifying separate classes, not the entire module here
@@ -103,8 +102,7 @@ def test_inheritance_diagram(app, status, warning):
             ('dummy.test.F', 'dummy.test.F', ['dummy.test.C'], None),
             ('dummy.test.C', 'dummy.test.C', [], None),
             ('dummy.test.E', 'dummy.test.E', ['dummy.test.B'], None),
-                        ('dummy.test.D', 'dummy.test.D',
+            ('dummy.test.D', 'dummy.test.D', ['dummy.test.B', 'dummy.test.C'], None),
-                            ['dummy.test.B', 'dummy.test.C'], None),
             ('dummy.test.B', 'dummy.test.B', [], None)
         ]
 
@@ -126,8 +124,7 @@ def test_inheritance_diagram(app, status, warning):
             ('dummy.test.F', 'dummy.test.F', ['dummy.test.C'], None),
             ('dummy.test.C', 'dummy.test.C', [], None),
             ('dummy.test.E', 'dummy.test.E', ['dummy.test.B'], None),
-                        ('dummy.test.D', 'dummy.test.D',
+            ('dummy.test.D', 'dummy.test.D', ['dummy.test.B', 'dummy.test.C'], None),
-                            ['dummy.test.B', 'dummy.test.C'], None),
             ('dummy.test.B', 'dummy.test.B', [], None),
             ('dummy.test.A', 'dummy.test.A', [], None),
         ]

tests/test_ext_intersphinx.py

@@ -9,22 +9,22 @@
     :license: BSD, see LICENSE for details.
 """
 
+import os
 import unittest
+from io import BytesIO
 
-from docutils import nodes
 import mock
 import pytest
 import requests
-from io import BytesIO
+from docutils import nodes
-import os
+from test_util_inventory import inventory_v2, inventory_v2_not_having_version
 
 from sphinx import addnodes
-from sphinx.ext.intersphinx import setup as intersphinx_setup
 from sphinx.ext.intersphinx import (
     load_mappings, missing_reference, _strip_basic_auth,
     _get_safe_url, fetch_inventory, INVENTORY_FILENAME, debug
 )
-from test_util_inventory import inventory_v2, inventory_v2_not_having_version
+from sphinx.ext.intersphinx import setup as intersphinx_setup
 
 
 def fake_node(domain, type, target, content, **attrs):

tests/test_ext_math.py

@@ -9,9 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os
-import re
 import errno
+import re
 import subprocess
 
 import pytest
@@ -37,10 +36,12 @@ def test_jsmath(app, status, warning):
     content = (app.outdir / 'math.html').text()
 
     assert '<div class="math notranslate">\na^2 + b^2 = c^2</div>' in content
-    assert '<div class="math notranslate">\n\\begin{split}a + 1 &lt; b\\end{split}</div>' in content
+    assert ('<div class="math notranslate">\n\\begin{split}a + 1 &lt; b\\end{split}</div>'
+            in content)
     assert (u'<span class="eqno">(1)<a class="headerlink" href="#equation-foo" '
             u'title="Permalink to this equation">\xb6</a></span>'
-            u'<div class="math notranslate" id="equation-foo">\ne^{i\\pi} = 1</div>' in content)
+            u'<div class="math notranslate" id="equation-foo">\ne^{i\\pi} = 1</div>'
+            in content)
     assert (u'<span class="eqno">(2)<a class="headerlink" href="#equation-math-0" '
             u'title="Permalink to this equation">\xb6</a></span>'
             u'<div class="math notranslate" id="equation-math-0">\n'

tests/test_ext_napoleon.py

@@ -13,11 +13,11 @@
 from collections import namedtuple
 from unittest import TestCase
 
-from sphinx.application import Sphinx
-from sphinx.ext.napoleon import (_process_docstring, _skip_member, Config,
-                                 setup)
 import mock
 
+from sphinx.application import Sphinx
+from sphinx.ext.napoleon import _process_docstring, _skip_member, Config, setup
+
 
 def _private_doc():
     """module._private_doc.DOCSTRING"""

tests/test_ext_napoleon_docstring.py

@@ -11,15 +11,14 @@
 """
 
 from collections import namedtuple
-
-# inspect.cleandoc() implements the trim() function from PEP 257
 from inspect import cleandoc
 from textwrap import dedent
 from unittest import TestCase
 
+import mock
+
 from sphinx.ext.napoleon import Config
 from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring
-import mock
 
 
 class NamedtupleSubclass(namedtuple('NamedtupleSubclass', ('attr1', 'attr2'))):

tests/test_ext_napoleon_iterators.py

@@ -10,9 +10,10 @@
     :license: BSD, see LICENSE for details.
 """
 
-from sphinx.ext.napoleon.iterators import peek_iter, modify_iter
 from unittest import TestCase
 
+from sphinx.ext.napoleon.iterators import peek_iter, modify_iter
+
 
 class BaseIteratorsTest(TestCase):
     def assertEqualTwice(self, expected, func, *args):

tests/test_highlighting.py

@@ -10,9 +10,9 @@
 """
 
 import mock
+from pygments.formatters.html import HtmlFormatter
 from pygments.lexer import RegexLexer
 from pygments.token import Text, Name
-from pygments.formatters.html import HtmlFormatter
 
 from sphinx.highlighting import PygmentsBridge
 

tests/test_intl.py

@@ -12,13 +12,13 @@
 from __future__ import print_function
 
 import os
-import re
 import pickle
-from docutils import nodes
+import re
 
-from babel.messages import pofile, mofile
-from six import string_types
 import pytest
+from babel.messages import pofile, mofile
+from docutils import nodes
+from six import string_types
 
 from sphinx.testing.util import (
     path, etree_parse, strip_escseq,

tests/test_markup.py

@@ -9,21 +9,20 @@
     :license: BSD, see LICENSE for details.
 """
 
-import re
 import pickle
+import re
 
+import pytest
 from docutils import frontend, utils, nodes
 from docutils.parsers.rst import Parser as RstParser
 from docutils.transforms.universal import SmartQuotes
 
 from sphinx import addnodes
+from sphinx.testing.util import assert_node
 from sphinx.util import texescape
 from sphinx.util.docutils import sphinx_domains
 from sphinx.writers.html import HTMLWriter, HTMLTranslator
 from sphinx.writers.latex import LaTeXWriter, LaTeXTranslator
-import pytest
-
-from sphinx.testing.util import assert_node
 
 
 @pytest.fixture

tests/test_pycode.py

@@ -10,6 +10,7 @@
 """
 
 import os
+
 from six import PY2
 
 import sphinx

tests/test_quickstart.py

@@ -12,9 +12,9 @@
 import sys
 import time
 
+import pytest
 from six import PY2, text_type, StringIO
 from six.moves import input
-import pytest
 
 from sphinx import application
 from sphinx.cmd import quickstart as qs

tests/test_search.py

@@ -11,13 +11,13 @@
 
 from collections import namedtuple
 
-from six import BytesIO
+import pytest
 from docutils import frontend, utils
 from docutils.parsers import rst
+from six import BytesIO
 
 from sphinx.search import IndexBuilder
 from sphinx.util import jsdump
-import pytest
 
 DummyEnvironment = namedtuple('DummyEnvironment', ['version', 'domains'])
 

tests/test_setup_command.py

@@ -10,15 +10,15 @@
 """
 
 import os
-import sys
 import subprocess
+import sys
 from collections import namedtuple
-import sphinx
+from textwrap import dedent
 
 import pytest
 
+import sphinx
 from sphinx.util.osutil import cd
-from textwrap import dedent
 
 
 @pytest.fixture

tests/test_smartquotes.py

@@ -10,6 +10,7 @@
 """
 
 import pytest
+
 from sphinx.util import docutils
 
 

tests/test_templating.py

@@ -10,6 +10,7 @@
 """
 
 import pytest
+
 from sphinx.ext.autosummary.generate import setup_documenters
 
 

tests/test_util.py

@@ -12,12 +12,11 @@
 import pytest
 from mock import patch
 
-from sphinx.util import logging
+from sphinx.testing.util import strip_escseq
 from sphinx.util import (
     display_chunk, encode_uri, parselinenos, status_iterator, xmlname_checker
 )
-
+from sphinx.util import logging
-from sphinx.testing.util import strip_escseq
 
 
 def test_encode_uri():

tests/test_util_fileutil.py

@@ -8,11 +8,12 @@
     :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
-from sphinx.util.fileutil import copy_asset, copy_asset_file
-from sphinx.jinja2glue import BuiltinTemplateLoader
 
 import mock
 
+from sphinx.jinja2glue import BuiltinTemplateLoader
+from sphinx.util.fileutil import copy_asset, copy_asset_file
+
 
 class DummyTemplateLoader(BuiltinTemplateLoader):
     def __init__(self):

tests/test_util_i18n.py

@@ -10,13 +10,14 @@
 """
 from __future__ import print_function
 
-import os
 import datetime
+import os
 
 import pytest
 from babel.messages.mofile import read_mo
-from sphinx.util import i18n
+
 from sphinx.errors import SphinxError
+from sphinx.util import i18n
 
 
 def test_catalog_info_for_file_and_path():

tests/test_util_inspect.py

@@ -8,11 +8,12 @@
     :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
-import sys
-from six import PY3
 import functools
+import sys
 from textwrap import dedent
+
 import pytest
+from six import PY3
 
 from sphinx.util import inspect
 

tests/test_util_inventory.py

@@ -9,8 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
-import zlib
 import posixpath
+import zlib
 
 from six import BytesIO