Merge branch '1.7'

CHANGES

@@ -202,6 +202,13 @@ Bugs fixed
 * #5091: latex: curly braces in index entries are not handled correctly
 * #5070: epub: Wrong internal href fragment links
 * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed
+* #5076: napoleon raises RuntimeError with python 3.7
+* #5125: sphinx-build: Interface of ``sphinx:main()`` has changed
+* sphinx-build: ``sphinx.cmd.build.main()`` refers ``sys.argv`` instead of given
+  argument
+* #5146: autosummary: warning is emitted when the first line of docstring ends
+  with literal notation
+* autosummary: warnings of autosummary indicates wrong location (refs: #5146)
 
 Testing
 --------

sphinx/__init__.py

@@ -71,16 +71,16 @@ if __version__.endswith('+'):
         pass
 
 
-def main(*args, **kwargs):
-    # type: (Any, Any) -> int
+def main(argv=sys.argv):  # type: ignore
+    # type: (List[unicode]) -> int
     from .cmd import build
     warnings.warn(
         '`sphinx.main()` has moved to `sphinx.cmd.build.main()`.',
         RemovedInSphinx20Warning,
         stacklevel=2,
     )
-    args = args[1:]  # skip first argument to adjust arguments (refs: #4615)
-    return build.main(*args, **kwargs)
+    argv = argv[1:]  # skip first argument to adjust arguments (refs: #4615)
+    return build.main(argv)
 
 
 def build_main(argv=sys.argv):

sphinx/cmd/build.py

@@ -311,7 +311,7 @@ def main(argv=sys.argv[1:]):  # type: ignore
     locale.setlocale(locale.LC_ALL, '')
     sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')
 
-    if sys.argv[1:2] == ['-M']:
+    if argv[:1] == ['-M']:
         return make_main(argv)
     else:
         return build_main(argv)

sphinx/config.py

@@ -129,7 +129,7 @@ class Config(object):
         rst_epilog = (None, 'env', string_classes),
         rst_prolog = (None, 'env', string_classes),
         trim_doctest_flags = (True, 'env', []),
-        primary_domain = ('py', 'env', [NoneType]),
+        primary_domain = ('py', 'env', [NoneType]),   # type: ignore
         needs_sphinx = (None, None, string_classes),
         needs_extensions = ({}, None, []),
         manpages_url = (None, 'env', []),

sphinx/ext/autosummary/__init__.py

@@ -78,7 +78,7 @@ from sphinx.ext.autodoc.importer import import_module
 from sphinx.locale import __
 from sphinx.pycode import ModuleAnalyzer, PycodeError
 from sphinx.util import import_object, rst, logging
-from sphinx.util.docutils import NullReporter, SphinxDirective, new_document
+from sphinx.util.docutils import NullReporter, SphinxDirective, new_document, switch_source_input
 
 if False:
     # For type annotation
@@ -92,6 +92,7 @@ logger = logging.getLogger(__name__)
 
 
 periods_re = re.compile(r'\.(?:\s+)')
+literal_re = re.compile(r'::\s*$')
 
 
 # -- autosummary_toc node ------------------------------------------------------
@@ -373,17 +374,19 @@ class Autosummary(SphinxDirective):
         def append_row(*column_texts):
             # type: (unicode) -> None
             row = nodes.row('')
+            source, line = self.state_machine.get_source_and_line()
             for text in column_texts:
                 node = nodes.paragraph('')
                 vl = ViewList()
-                vl.append(text, '<autosummary>')
-                self.state.nested_parse(vl, 0, node)
-                try:
-                    if isinstance(node[0], nodes.paragraph):
-                        node = node[0]
-                except IndexError:
-                    pass
-                row.append(nodes.entry('', node))
+                vl.append(text, '%s:%d:<autosummary>' % (source, line))
+                with switch_source_input(self.state, vl):
+                    self.state.nested_parse(vl, 0, node)
+                    try:
+                        if isinstance(node[0], nodes.paragraph):
+                            node = node[0]
+                    except IndexError:
+                        pass
+                    row.append(nodes.entry('', node))
             body.append(row)
 
         for name, sig, summary, real_name in items:
@@ -484,6 +487,9 @@ def extract_summary(doc, document):
                 # considered as that splitting by period does not break inline markups
                 break
 
+    # strip literal notation mark ``::`` from tail of summary
+    summary = literal_re.sub('.', summary)
+
     return summary
 
 

sphinx/ext/autosummary/generate.py

@@ -124,7 +124,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
     else:
         if template_dir:
             template_dirs.insert(0, template_dir)
-        template_loader = FileSystemLoader(template_dirs)  # type: ignore
+        template_loader = FileSystemLoader(template_dirs)
     template_env = SandboxedEnvironment(loader=template_loader)
     template_env.filters['underline'] = _underline
 

sphinx/ext/napoleon/docstring.py

@@ -556,7 +556,14 @@ class GoogleDocstring(UnicodeMixin):
         self._parsed_lines = self._consume_empty()
 
         if self._name and (self._what == 'attribute' or self._what == 'data'):
-            self._parsed_lines.extend(self._parse_attribute_docstring())
+            # Implicit stop using StopIteration no longer allowed in
+            # Python 3.7; see PEP 479
+            res = []  # type: List[unicode]
+            try:
+                res = self._parse_attribute_docstring()
+            except StopIteration:
+                pass
+            self._parsed_lines.extend(res)
             return
 
         while self._line_iter.has_next():

sphinx/locale/__init__.py

@@ -64,7 +64,7 @@ class _TranslationProxy(UserString, object):
     # replace function from UserString; it instantiates a self.__class__
     # for the encoding result
 
-    def encode(self, encoding=None, errors=None):
+    def encode(self, encoding=None, errors=None):  # type: ignore
         # type: (unicode, unicode) -> str
         if encoding:
             if errors:
@@ -88,7 +88,7 @@ class _TranslationProxy(UserString, object):
         return dir(text_type)
 
     def __iter__(self):
-        # type: () -> Iterator[unicode]
+        # type: () -> Iterator
         return iter(self.data)
 
     def __len__(self):
@@ -103,15 +103,15 @@ class _TranslationProxy(UserString, object):
         # type: () -> unicode
         return text_type(self.data)
 
-    def __add__(self, other):
+    def __add__(self, other):  # type: ignore
         # type: (unicode) -> unicode
         return self.data + other
 
-    def __radd__(self, other):
+    def __radd__(self, other):  # type: ignore
         # type: (unicode) -> unicode
         return other + self.data
 
-    def __mod__(self, other):
+    def __mod__(self, other):  # type: ignore
         # type: (unicode) -> unicode
         return self.data % other
 
@@ -119,11 +119,11 @@ class _TranslationProxy(UserString, object):
         # type: (unicode) -> unicode
         return other % self.data
 
-    def __mul__(self, other):
+    def __mul__(self, other):  # type: ignore
         # type: (Any) -> unicode
         return self.data * other
 
-    def __rmul__(self, other):
+    def __rmul__(self, other):  # type: ignore
         # type: (Any) -> unicode
         return other * self.data
 
@@ -165,7 +165,7 @@ class _TranslationProxy(UserString, object):
         # type: (Tuple[Callable, Tuple[unicode]]) -> None
         self._func, self._args = tup
 
-    def __getitem__(self, key):
+    def __getitem__(self, key):  # type: ignore
         # type: (Any) -> unicode
         return self.data[key]
 

tests/test_ext_autosummary.py

@@ -81,6 +81,10 @@ def test_extract_summary(capsys):
     doc = ['Blabla, i.e. bla.']
     assert extract_summary(doc, document) == 'Blabla, i.e.'
 
+    # literal
+    doc = ['blah blah::']
+    assert extract_summary(doc, document) == 'blah blah.'
+
     _, err = capsys.readouterr()
     assert err == ''