Merge pull request #5703 from tk0miya/fix_typehints_for_builders

Fix annotations for builders

14 files changed, 71 insertions, 67 deletions

diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py
index 27f16dee0..ad8097dba 100644
--- a/sphinx/builders/_epub_base.py
+++ b/sphinx/builders/_epub_base.py
@@ -160,6 +160,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         self.tocid = 0
         self.id_cache = {}  # type: Dict[unicode, unicode]
         self.use_index = self.get_builder_config('use_index', 'epub')
+        self.refnodes = []  # type: List[Dict[unicode, Any]]
 
     def create_build_info(self):
         # type: () -> BuildInfo
@@ -210,8 +211,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
                         'text': ssp(self.esc(doctree.astext()))
                     })
                     break
-        else:
-            for elem in doctree.children:
+        elif isinstance(doctree, nodes.Element):
+            for elem in doctree:
                 result = self.get_refnodes(elem, result)
         return result
 
@@ -280,7 +281,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     target['ids'][i] = self.fix_fragment('', node_id)
 
             next_node = target.next_node(siblings=True)
-            if next_node and isinstance(next_node, nodes.Element):
+            if isinstance(next_node, nodes.Element):
                 for i, node_id in enumerate(next_node['ids']):
                     if ':' in node_id:
                         next_node['ids'][i] = self.fix_fragment('', node_id)
@@ -316,7 +317,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
             return footnote
 
         def footnote_spot(tree):
-            # type: (nodes.document) -> Tuple[nodes.Node, int]
+            # type: (nodes.document) -> Tuple[nodes.document, int]
             """Find or create a spot to place footnotes.
 
             The function returns the tuple (parent, index)."""
@@ -377,7 +378,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         super(EpubBuilder, self).write_doc(docname, doctree)
 
     def fix_genindex(self, tree):
-        # type: (nodes.Node) -> None
+        # type: (List[Tuple[unicode, List[Tuple[unicode, Any]]]]) -> None
         """Fix href attributes for genindex pages."""
         # XXX: modifies tree inline
         # Logic modeled from themes/basic/genindex.html
@@ -625,7 +626,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                         metadata)
 
     def new_navpoint(self, node, level, incr=True):
-        # type: (nodes.Node, int, bool) -> NavPoint
+        # type: (Dict[unicode, Any], int, bool) -> NavPoint
         """Create a new entry in the toc from the node at given level."""
         # XXX Modifies the node
         if incr:
@@ -635,7 +636,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                         node['text'], node['refuri'], [])
 
     def build_navpoints(self, nodes):
-        # type: (nodes.Node) -> List[NavPoint]
+        # type: (List[Dict[unicode, Any]]) -> List[NavPoint]
         """Create the toc navigation structure.
 
         Subelements of a node are nested inside the navpoint.  For nested nodes
diff --git a/sphinx/builders/applehelp.py b/sphinx/builders/applehelp.py
index 309053d56..9add1bbd1 100644
--- a/sphinx/builders/applehelp.py
+++ b/sphinx/builders/applehelp.py
@@ -166,8 +166,8 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
             info_plist['HPDBookRemoteURL'] = self.config.applehelp_remote_url
 
         logger.info(bold(__('writing Info.plist... ')), nonl=True)
-        with open(path.join(contents_dir, 'Info.plist'), 'wb') as f:
-            plistlib.dump(info_plist, f)  # type: ignore
+        with open(path.join(contents_dir, 'Info.plist'), 'wb') as fb:
+            plistlib.dump(info_plist, fb)  # type: ignore
         logger.info(__('done'))
 
         # Copy the icon, if one is supplied
@@ -186,8 +186,8 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
 
         # Build the access page
         logger.info(bold(__('building access page...')), nonl=True)
-        with open(path.join(language_dir, '_access.html'), 'w') as f:
-            f.write(access_page_template % {
+        with open(path.join(language_dir, '_access.html'), 'w') as ft:
+            ft.write(access_page_template % {
                 'toc': htmlescape(toc, quote=True),
                 'title': htmlescape(self.config.applehelp_title)
             })
diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py
index db7399a48..1bf2f2a56 100644
--- a/sphinx/builders/devhelp.py
+++ b/sphinx/builders/devhelp.py
@@ -90,7 +90,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder):
             self.config.master_doc, self, prune_toctrees=False)
 
         def write_toc(node, parent):
-            # type: (nodes.Node, nodes.Node) -> None
+            # type: (nodes.Node, etree.Element) -> None
             if isinstance(node, addnodes.compact_paragraph) or \
                isinstance(node, nodes.bullet_list):
                 for subnode in node:
@@ -104,7 +104,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder):
                 parent.attrib['name'] = node.astext()
 
         matcher = NodeMatcher(addnodes.compact_paragraph, toctree=Any)
-        for node in tocdoc.traverse(matcher):
+        for node in tocdoc.traverse(matcher):  # type: addnodes.compact_paragraph
             write_toc(node, chapters)
 
         # Index
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index 04c992627..312098098 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -151,7 +151,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
         self.globalcontext['skip_ua_compatible'] = True
 
     def build_navlist(self, navnodes):
-        # type: (List[nodes.Node]) -> List[NavPoint]
+        # type: (List[Dict[unicode, Any]]) -> List[NavPoint]
         """Create the toc navigation structure.
 
         This method is almost same as build_navpoints method in epub.py.
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index aa5c36ac0..386dfe476 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -590,7 +590,7 @@ class StandaloneHTMLBuilder(Builder):
         self.globalcontext.update(self.config.html_context)
 
     def get_doc_context(self, docname, body, metatags):
-        # type: (unicode, unicode, Dict) -> Dict[unicode, Any]
+        # type: (unicode, unicode, unicode) -> Dict[unicode, Any]
         """Collect items for the template context of a page."""
         # find out relations
         prev = next = None
@@ -633,8 +633,8 @@ class StandaloneHTMLBuilder(Builder):
         parents.reverse()
 
         # title rendered as HTML
-        title = self.env.longtitles.get(docname)
-        title = title and self.render_partial(title)['title'] or ''
+        title_node = self.env.longtitles.get(docname)
+        title = title_node and self.render_partial(title_node)['title'] or ''
 
         # Suffix for the document
         source_suffix = path.splitext(self.env.doc2path(docname))[1]
@@ -689,11 +689,11 @@ class StandaloneHTMLBuilder(Builder):
         self.handle_page(docname, ctx, event_arg=doctree)
 
     def write_doc_serialized(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         self.imgpath = relative_uri(self.get_target_uri(docname), self.imagedir)
         self.post_process_images(doctree)
-        title = self.env.longtitles.get(docname)
-        title = title and self.render_partial(title)['title'] or ''
+        title_node = self.env.longtitles.get(docname)
+        title = title_node and self.render_partial(title_node)['title'] or ''
         self.index_page(docname, doctree, title)
 
     def finish(self):
@@ -970,7 +970,7 @@ class StandaloneHTMLBuilder(Builder):
         self.indexer.prune(keep)
 
     def index_page(self, pagename, doctree, title):
-        # type: (unicode, nodes.Node, unicode) -> None
+        # type: (unicode, nodes.document, unicode) -> None
         # only index pages with title
         if self.indexer is not None and title:
             filename = self.env.doc2path(pagename, base=None)
@@ -1322,14 +1322,13 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         return {self.config.master_doc: new_fignumbers}
 
     def get_doc_context(self, docname, body, metatags):
-        # type: (unicode, unicode, Dict) -> Dict
+        # type: (unicode, unicode, unicode) -> Dict
         # no relation links...
-        toc = TocTree(self.env).get_toctree_for(self.config.master_doc,
-                                                self, False)
+        toctree = TocTree(self.env).get_toctree_for(self.config.master_doc, self, False)
         # if there is no toctree, toc is None
-        if toc:
-            self.fix_refuris(toc)
-            toc = self.render_partial(toc)['fragment']
+        if toctree:
+            self.fix_refuris(toctree)
+            toc = self.render_partial(toctree)['fragment']
             display_toc = True
         else:
             toc = ''
diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py
index 9ba7ae9b0..1588e61fd 100644
--- a/sphinx/builders/htmlhelp.py
+++ b/sphinx/builders/htmlhelp.py
@@ -22,6 +22,7 @@ from sphinx.config import string_classes
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util.nodes import NodeMatcher
 from sphinx.util.osutil import make_filename_from_project
 from sphinx.util.pycompat import htmlescape
 
@@ -294,11 +295,8 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
                     for subnode in node:
                         write_toc(subnode, ullevel)
 
-            def istoctree(node):
-                # type: (nodes.Node) -> bool
-                return isinstance(node, addnodes.compact_paragraph) and \
-                    'toctree' in node
-            for node in tocdoc.traverse(istoctree):
+            matcher = NodeMatcher(addnodes.compact_paragraph, toctree=True)
+            for node in tocdoc.traverse(matcher):  # type: addnodes.compact_paragraph
                 write_toc(node)
             f.write(contents_footer)
 
diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py
index 4c3150c68..1b4360cf9 100644
--- a/sphinx/builders/latex/transforms.py
+++ b/sphinx/builders/latex/transforms.py
@@ -35,7 +35,8 @@ class FootnoteDocnameUpdater(SphinxTransform):
 
     def apply(self, **kwargs):
         # type: (Any) -> None
-        for node in self.document.traverse(NodeMatcher(*self.TARGET_NODES)):
+        matcher = NodeMatcher(*self.TARGET_NODES)
+        for node in self.document.traverse(matcher):  # type: nodes.Element
             node['docname'] = self.env.docname
 
 
@@ -544,10 +545,10 @@ class CitationReferenceTransform(SphinxTransform):
 
         matcher = NodeMatcher(addnodes.pending_xref, refdomain='std', reftype='citation')
         citations = self.env.get_domain('std').data['citations']
-        for node in self.document.traverse(matcher):
+        for node in self.document.traverse(matcher):  # type: addnodes.pending_xref
             docname, labelid, _ = citations.get(node['reftarget'], ('', '', 0))
             if docname:
-                citation_ref = nodes.citation_reference('', *node.children,
+                citation_ref = nodes.citation_reference('', '', *node.children,
                                                         docname=docname, refname=labelid)
                 node.replace_self(citation_ref)
 
@@ -584,7 +585,7 @@ class LiteralBlockTransform(SphinxTransform):
             return
 
         matcher = NodeMatcher(nodes.container, literal_block=True)
-        for node in self.document.traverse(matcher):
+        for node in self.document.traverse(matcher):  # type: nodes.container
             newnode = captioned_literal_block('', *node.children, **node.attributes)
             node.replace_self(newnode)
 
diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py
index ca0119465..0ffc1b4c1 100644
--- a/sphinx/builders/linkcheck.py
+++ b/sphinx/builders/linkcheck.py
@@ -26,6 +26,7 @@ from sphinx.util import encode_uri, requests, logging
 from sphinx.util.console import (  # type: ignore
     purple, red, darkgreen, darkgray, darkred, turquoise
 )
+from sphinx.util.nodes import traverse_parent
 from sphinx.util.requests import is_ssl_error
 
 if False:
@@ -277,11 +278,10 @@ class CheckExternalLinksBuilder(Builder):
                 continue
             uri = node['refuri']
             lineno = None
-            while lineno is None:
-                node = node.parent
-                if node is None:
+            for parent in traverse_parent(node):
+                if parent.line:
+                    lineno = parent.line
                     break
-                lineno = node.line
             self.wqueue.put((uri, docname, lineno), False)
             n += 1
         done = 0
diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py
index 4179a9707..a6305856e 100644
--- a/sphinx/builders/qthelp.py
+++ b/sphinx/builders/qthelp.py
@@ -13,6 +13,7 @@ import os
 import posixpath
 import re
 from os import path
+from typing import Iterable, cast
 
 from docutils import nodes
 
@@ -23,6 +24,7 @@ from sphinx.config import string_classes
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util.nodes import NodeMatcher
 from sphinx.util.osutil import make_filename
 from sphinx.util.pycompat import htmlescape
 from sphinx.util.template import SphinxRenderer
@@ -101,12 +103,9 @@ class QtHelpBuilder(StandaloneHTMLBuilder):
         tocdoc = self.env.get_and_resolve_doctree(self.config.master_doc, self,
                                                   prune_toctrees=False)
 
-        def istoctree(node):
-            # type: (nodes.Node) -> bool
-            return isinstance(node, addnodes.compact_paragraph) and \
-                'toctree' in node
         sections = []
-        for node in tocdoc.traverse(istoctree):
+        matcher = NodeMatcher(addnodes.compact_paragraph, toctree=True)
+        for node in tocdoc.traverse(matcher):  # type: addnodes.compact_paragraph
             sections.extend(self.write_toc(node))
 
         for indexname, indexcls, content, collapse in self.domain_indices:
@@ -164,26 +163,30 @@ class QtHelpBuilder(StandaloneHTMLBuilder):
             return False
         if len(node.children) != 2:
             return False
-        if not isinstance(node.children[0], addnodes.compact_paragraph):
+        if not isinstance(node[0], addnodes.compact_paragraph):
             return False
-        if not isinstance(node.children[0][0], nodes.reference):
+        if not isinstance(node[0][0], nodes.reference):
             return False
-        if not isinstance(node.children[1], nodes.bullet_list):
+        if not isinstance(node[1], nodes.bullet_list):
             return False
         return True
 
     def write_toc(self, node, indentlevel=4):
         # type: (nodes.Node, int) -> List[unicode]
         parts = []  # type: List[unicode]
-        if self.isdocnode(node):
-            refnode = node.children[0][0]
-            link = refnode['refuri']
-            title = htmlescape(refnode.astext()).replace('"', '"')
+        if isinstance(node, nodes.list_item) and self.isdocnode(node):
+            compact_paragraph = cast(addnodes.compact_paragraph, node[0])
+            reference = cast(nodes.reference, compact_paragraph[0])
+            link = reference['refuri']
+            title = htmlescape(reference.astext()).replace('"', '"')
             item = '<section title="%(title)s" ref="%(ref)s">' % \
                 {'title': title, 'ref': link}
             parts.append(' ' * 4 * indentlevel + item)
-            for subnode in node.children[1]:
-                parts.extend(self.write_toc(subnode, indentlevel + 1))
+
+            bullet_list = cast(nodes.bullet_list, node[1])
+            list_items = cast(Iterable[nodes.list_item], bullet_list)
+            for list_item in list_items:
+                parts.extend(self.write_toc(list_item, indentlevel + 1))
             parts.append(' ' * 4 * indentlevel + '</section>')
         elif isinstance(node, nodes.list_item):
             for subnode in node:
diff --git a/sphinx/builders/xml.py b/sphinx/builders/xml.py
index 4bc0d27e2..3fdc21244 100644
--- a/sphinx/builders/xml.py
+++ b/sphinx/builders/xml.py
@@ -23,7 +23,8 @@ from sphinx.writers.xml import XMLWriter, PseudoXMLWriter
 
 if False:
     # For type annotation
-    from typing import Any, Dict, Iterator, Set  # NOQA
+    from typing import Any, Dict, Iterator, Set, Type  # NOQA
+    from docutils.writers.xml import BaseXMLWriter  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.util.typing import unicode  # NOQA
 
@@ -41,7 +42,7 @@ class XMLBuilder(Builder):
     out_suffix = '.xml'
     allow_parallel = True
 
-    _writer_class = XMLWriter
+    _writer_class = XMLWriter  # type: Type[BaseXMLWriter]
     default_translator_class = XMLTranslator
 
     def init(self):
diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py
index 185e35956..3806b86ba 100644
--- a/sphinx/ext/mathbase.py
+++ b/sphinx/ext/mathbase.py
@@ -24,9 +24,9 @@ from sphinx.domains.math import MathReferenceRole as EqXRefRole  # NOQA  # to ke
 if False:
     # For type annotation
     from typing import Any, Callable, List, Tuple  # NOQA
-    from docutils.writers.html4css1 import Writer  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.util.typing import unicode  # NOQA
+    from sphinx.writers.html import HTMLTranslator  # NOQA
 
 
 class MathDirective(MathDirectiveBase):
@@ -45,7 +45,7 @@ def math_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
 
 
 def get_node_equation_number(writer, node):
-    # type: (Writer, nodes.Node) -> unicode
+    # type: (HTMLTranslator, nodes.math_block) -> unicode
     warnings.warn('sphinx.ext.mathbase.get_node_equation_number() is moved to '
                   'sphinx.util.math package.',
                   RemovedInSphinx30Warning, stacklevel=2)
diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py
index 0c6fde87e..bb6d807fe 100644
--- a/sphinx/util/nodes.py
+++ b/sphinx/util/nodes.py
@@ -279,7 +279,7 @@ def extract_messages(doctree):
 
 
 def find_source_node(node):
-    # type: (nodes.Node) -> unicode
+    # type: (nodes.Element) -> unicode
     for pnode in traverse_parent(node):
         if pnode.source:
             return pnode.source
@@ -287,7 +287,7 @@ def find_source_node(node):
 
 
 def traverse_parent(node, cls=None):
-    # type: (nodes.Node, Any) -> Iterable[nodes.Node]
+    # type: (nodes.Element, Any) -> Iterable[nodes.Element]
     while node:
         if cls is None or isinstance(node, cls):
             yield node
@@ -390,7 +390,7 @@ def process_index_entry(entry, targetid):
 
 
 def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed):
-    # type: (Builder, Set[unicode], unicode, nodes.document, Callable, List[unicode]) -> nodes.Element  # NOQA
+    # type: (Builder, Set[unicode], unicode, nodes.document, Callable, List[unicode]) -> nodes.document  # NOQA
     """Inline all toctrees in the *tree*.
 
     Record all docnames in *docnameset*, and output docnames with *colorfunc*.
diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
index a7750ea4f..e2cfe9880 100644
--- a/sphinx/writers/latex.py
+++ b/sphinx/writers/latex.py
@@ -17,6 +17,7 @@ import sys
 import warnings
 from collections import defaultdict
 from os import path
+from typing import Iterable, cast
 
 from docutils import nodes, writers
 from docutils.writers.latex2e import Babel
@@ -254,7 +255,7 @@ class LaTeXWriter(writers.Writer):
         # type: () -> None
         visitor = self.builder.create_translator(self.document, self.builder)
         self.document.walkabout(visitor)
-        self.output = visitor.astext()
+        self.output = cast(LaTeXTranslator, visitor).astext()
 
 
 # Helper classes
@@ -1443,9 +1444,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
         # type: (addnodes.acks) -> None
         # this is a list in the source, but should be rendered as a
         # comma-separated list here
+        bullet_list = cast(nodes.bullet_list, node[0])
+        list_items = cast(Iterable[nodes.list_item], bullet_list)
         self.body.append('\n\n')
-        self.body.append(', '.join(n.astext()
-                                   for n in node.children[0].children) + '.')
+        self.body.append(', '.join(n.astext() for n in list_items) + '.')
         self.body.append('\n\n')
         raise nodes.SkipNode
 
@@ -1640,7 +1642,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         pass
 
     def latex_image_length(self, width_str):
-        # type: (nodes.Node) -> unicode
+        # type: (unicode) -> unicode
         try:
             return rstdim_to_latexdim(width_str)
         except ValueError:
diff --git a/sphinx/writers/xml.py b/sphinx/writers/xml.py
index 2a18c173c..28510c587 100644
--- a/sphinx/writers/xml.py
+++ b/sphinx/writers/xml.py
@@ -9,7 +9,6 @@
     :license: BSD, see LICENSE for details.
 """
 
-from docutils import writers
 from docutils.writers.docutils_xml import Writer as BaseXMLWriter
 
 if False:
@@ -37,7 +36,7 @@ class XMLWriter(BaseXMLWriter):
         return super(XMLWriter, self).translate()
 
 
-class PseudoXMLWriter(writers.Writer):
+class PseudoXMLWriter(BaseXMLWriter):
 
     supported = ('pprint', 'pformat', 'pseudoxml')
     """Formats this writer supports."""