Merge pull request #5691 from tk0miya/fix_typehints_for_ext

Fix annotations for extensions

sphinx/ext/autosummary/__init__.py

@@ -59,6 +59,7 @@ import posixpath
 import re
 import sys
 from types import ModuleType
+from typing import List, cast
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -82,12 +83,13 @@ from sphinx.util.matching import Matcher
 
 if False:
     # For type annotation
-    from typing import Any, Dict, List, Tuple, Type, Union  # NOQA
-    from docutils.utils import Inliner  # NOQA
+    from typing import Any, Dict, Tuple, Type, Union  # NOQA
+    from docutils.parsers.rst.states import Inliner  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
     from sphinx.ext.autodoc import Documenter  # NOQA
     from sphinx.util.typing import N_co, unicode  # NOQA
+    from sphinx.writers.html import HTMLTranslator  # NOQA
 
 logger = logging.getLogger(__name__)
 
@@ -103,7 +105,7 @@ class autosummary_toc(nodes.comment):
 
 
 def process_autosummary_toc(app, doctree):
-    # type: (Sphinx, nodes.Node) -> None
+    # type: (Sphinx, nodes.document) -> None
     """Insert items described in autosummary:: to the TOC tree, but do
     not generate the toctree:: list.
     """
@@ -111,7 +113,7 @@ def process_autosummary_toc(app, doctree):
     crawled = {}
 
     def crawl_toc(node, depth=1):
-        # type: (nodes.Node, int) -> None
+        # type: (nodes.Element, int) -> None
         crawled[node] = True
         for j, subnode in enumerate(node):
             try:
@@ -146,13 +148,16 @@ class autosummary_table(nodes.comment):
 
 
 def autosummary_table_visit_html(self, node):
-    # type: (nodes.NodeVisitor, autosummary_table) -> None
+    # type: (HTMLTranslator, autosummary_table) -> None
     """Make the first column of the table non-breaking."""
     try:
-        tbody = node[0][0][-1]
-        for row in tbody:
-            col1_entry = row[0]
-            par = col1_entry[0]
+        table = cast(nodes.table, node[0])
+        tgroup = cast(nodes.tgroup, table[0])
+        tbody = cast(nodes.tbody, tgroup[-1])
+        rows = cast(List[nodes.row], tbody)
+        for row in rows:
+            col1_entry = cast(nodes.entry, row[0])
+            par = cast(nodes.paragraph, col1_entry[0])
             for j, subnode in enumerate(list(par)):
                 if isinstance(subnode, nodes.Text):
                     new_text = text_type(subnode.astext())
@@ -620,19 +625,22 @@ def autolink_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]):
     otherwise expands to '*text*'.
     """
     env = inliner.document.settings.env
-    r = None  # type: Tuple[List[nodes.Node], List[nodes.system_message]]
-    r = env.get_domain('py').role('obj')(
-        'obj', rawtext, etext, lineno, inliner, options, content)
-    pnode = r[0][0]
+    pyobj_role = env.get_domain('py').role('obj')
+    objects, msg = pyobj_role('obj', rawtext, etext, lineno, inliner, options, content)
+    if msg != []:
+        return objects, msg
 
+    assert len(objects) == 1
+    pending_xref = cast(addnodes.pending_xref, objects[0])
     prefixes = get_import_prefixes_from_env(env)
     try:
-        name, obj, parent, modname = import_by_name(pnode['reftarget'], prefixes)
+        name, obj, parent, modname = import_by_name(pending_xref['reftarget'], prefixes)
     except ImportError:
-        content_node = pnode[0]
-        r[0][0] = nodes.emphasis(rawtext, content_node[0].astext(),
-                                 classes=content_node['classes'])
-    return r
+        contnode = pending_xref[0]
+        objects[0] = nodes.emphasis(rawtext, contnode[0].astext(),
+                                    classes=contnode['classes'])
+
+    return objects, msg
 
 
 def get_rst_suffix(app):

sphinx/ext/autosummary/generate.py

@@ -42,8 +42,7 @@ from sphinx.util.rst import escape as rst_escape
 
 if False:
     # For type annotation
-    from typing import Any, Callable, Dict, List, Tuple, Type  # NOQA
-    from jinja2 import BaseLoader  # NOQA
+    from typing import Any, Callable, Dict, List, Tuple, Type, Union  # NOQA
     from sphinx import addnodes  # NOQA
     from sphinx.builders import Builder  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
@@ -117,7 +116,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
     template_dirs = [os.path.join(package_dir, 'ext',
                                   'autosummary', 'templates')]
 
-    template_loader = None  # type: BaseLoader
+    template_loader = None  # type: Union[BuiltinTemplateLoader, FileSystemLoader]
     if builder is not None:
         # allow the user to override the templates
         template_loader = BuiltinTemplateLoader()

sphinx/ext/doctest.py

@@ -428,7 +428,8 @@ Doctest summary
                 # type: (nodes.Node) -> bool
                 return isinstance(node, (nodes.literal_block, nodes.comment)) \
                     and 'testnodetype' in node
-        for node in doctree.traverse(condition):
+
+        for node in doctree.traverse(condition):  # type: nodes.Element
             source = node['test'] if 'test' in node else node.astext()
             filename = self.get_filename_for_node(node, docname)
             line_number = self.get_line_number(node)

sphinx/ext/graphviz.py

@@ -169,12 +169,13 @@ class Graphviz(SphinxDirective):
         if 'align' in self.options:
             node['align'] = self.options['align']
 
-        caption = self.options.get('caption')
-        if caption:
-            node = figure_wrapper(self, node, caption)
-
-        self.add_name(node)
-        return [node]
+        if 'caption' not in self.options:
+            self.add_name(node)
+            return [node]
+        else:
+            figure = figure_wrapper(self, node, self.options['caption'])
+            self.add_name(figure)
+            return [figure]
 
 
 class GraphvizSimple(SphinxDirective):
@@ -208,12 +209,13 @@ class GraphvizSimple(SphinxDirective):
         if 'align' in self.options:
             node['align'] = self.options['align']
 
-        caption = self.options.get('caption')
-        if caption:
-            node = figure_wrapper(self, node, caption)
-
-        self.add_name(node)
-        return [node]
+        if 'caption' not in self.options:
+            self.add_name(node)
+            return [node]
+        else:
+            figure = figure_wrapper(self, node, self.options['caption'])
+            self.add_name(figure)
+            return [figure]
 
 
 def render_dot(self, code, options, format, prefix='graphviz'):

sphinx/ext/inheritance_diagram.py

@@ -46,13 +46,16 @@ from docutils import nodes
 from docutils.parsers.rst import directives
 
 import sphinx
-from sphinx.ext.graphviz import render_dot_html, render_dot_latex, \
-    render_dot_texinfo, figure_wrapper
+from sphinx.ext.graphviz import (
+    graphviz, figure_wrapper,
+    render_dot_html, render_dot_latex, render_dot_texinfo
+)
 from sphinx.util.docutils import SphinxDirective
 
 if False:
     # For type annotation
     from typing import Any, Dict, List, Tuple, Dict, Optional  # NOQA
+    from sphinx import addnodes  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
     from sphinx.util.typing import N_co, unicode  # NOQA
@@ -314,7 +317,7 @@ class InheritanceGraph:
         return ''.join(res)
 
 
-class inheritance_diagram(nodes.General, nodes.Element):
+class inheritance_diagram(graphviz):
     """
     A docutils node to use as a placeholder for the inheritance diagram.
     """
@@ -375,11 +378,13 @@ class InheritanceDiagram(SphinxDirective):
         # dot file later
         node['graph'] = graph
 
-        # wrap the result in figure node
-        caption = self.options.get('caption')
-        if caption:
-            node = figure_wrapper(self, node, caption)
-        return [node]
+        if 'caption' not in self.options:
+            self.add_name(node)
+            return [node]
+        else:
+            figure = figure_wrapper(self, node, self.options['caption'])
+            self.add_name(figure)
+            return [figure]
 
 
 def get_graph_hash(node):
@@ -403,7 +408,7 @@ def html_visit_inheritance_diagram(self, node):
     graphviz_output_format = self.builder.env.config.graphviz_output_format.upper()
     current_filename = self.builder.current_docname + self.builder.out_suffix
     urls = {}
-    for child in node:
+    for child in node:  # type: addnodes.pending_xref
         if child.get('refuri') is not None:
             if graphviz_output_format == 'SVG':
                 urls[child['reftitle']] = "../" + child.get('refuri')

sphinx/ext/intersphinx.py

@@ -287,7 +287,7 @@ def load_mappings(app):
 
 
 def missing_reference(app, env, node, contnode):
-    # type: (Sphinx, BuildEnvironment, nodes.Element, nodes.TextElement) -> None
+    # type: (Sphinx, BuildEnvironment, nodes.Element, nodes.TextElement) -> nodes.reference
     """Attempt to resolve a missing reference via intersphinx references."""
     target = node['reftarget']
     inventories = InventoryAdapter(env)
@@ -302,10 +302,10 @@ def missing_reference(app, env, node, contnode):
         domain = node.get('refdomain')
         if not domain:
             # only objects in domains are in the inventory
-            return
+            return None
         objtypes = env.get_domain(domain).objtypes_for_role(node['reftype'])
         if not objtypes:
-            return
+            return None
         objtypes = ['%s:%s' % (domain, objtype) for objtype in objtypes]
     if 'std:cmdoption' in objtypes:
         # until Sphinx-1.6, cmdoptions are stored as std:option
@@ -361,6 +361,8 @@ def missing_reference(app, env, node, contnode):
         if len(contnode) and isinstance(contnode[0], nodes.Text):
             contnode[0] = nodes.Text(newtarget, contnode[0].rawsource)
 
+    return None
+
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]

sphinx/ext/todo.py

@@ -28,7 +28,7 @@ from sphinx.util.texescape import tex_escape_map
 
 if False:
     # For type annotation
-    from typing import Any, Dict, Iterable, List  # NOQA
+    from typing import Any, Dict, Iterable, List, Tuple  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.environment import BuildEnvironment  # NOQA
     from sphinx.util.typing import N_co, unicode  # NOQA
@@ -65,7 +65,7 @@ class Todo(BaseAdmonition, SphinxDirective):
         if not self.options.get('class'):
             self.options['class'] = ['admonition-todo']
 
-        (todo,) = super(Todo, self).run()
+        (todo,) = super(Todo, self).run()  # type: Tuple[nodes.Node]
         if isinstance(todo, nodes.system_message):
             return [todo]
         elif isinstance(todo, todo_node):
@@ -218,7 +218,7 @@ def merge_info(app, env, docnames, other):
 
 
 def visit_todo_node(self, node):
-    # type: (nodes.NodeVisitor, todo_node) -> None
+    # type: (HTMLTranslator, todo_node) -> None
     self.visit_admonition(node)
 
 
@@ -229,14 +229,16 @@ def depart_todo_node(self, node):
 
 def latex_visit_todo_node(self, node):
     # type: (LaTeXTranslator, todo_node) -> None
-    title = node.pop(0).astext().translate(tex_escape_map)
     self.body.append(u'\n\\begin{sphinxadmonition}{note}{')
     # If this is the original todo node, emit a label that will be referenced by
     # a hyperref in the todolist.
     target = node.get('targetref')
     if target is not None:
         self.body.append(u'\\label{%s}' % target)
-    self.body.append('%s:}' % title)
+
+    title_node = cast(nodes.title, node[0])
+    self.body.append('%s:}' % title_node.astext().translate(tex_escape_map))
+    node.pop(0)
 
 
 def latex_depart_todo_node(self, node):