Merge pull request #5680 from tk0miya/fix_typehints_for_builders

Fix annotations for builders

10 files changed, 87 insertions, 82 deletions

diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 16ec3e50d..94ec3b4ee 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -69,7 +69,7 @@ class Builder:
 
     #: default translator class for the builder.  This can be overrided by
     #: :py:meth:`app.set_translator()`.
-    default_translator_class = None  # type: nodes.NodeVisitor
+    default_translator_class = None  # type: Type[nodes.NodeVisitor]
     # doctree versioning method
     versioning_method = 'none'  # type: unicode
     versioning_compare = False
@@ -528,7 +528,7 @@ class Builder:
         self.write_doctree(docname, doctree)
 
     def write_doctree(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         """Write the doctree to a file."""
         # make it picklable
         doctree.reporter = None
@@ -587,7 +587,7 @@ class Builder:
     def _write_parallel(self, docnames, nproc):
         # type: (Sequence[unicode], int) -> None
         def write_process(docs):
-            # type: (List[Tuple[unicode, nodes.Node]]) -> None
+            # type: (List[Tuple[unicode, nodes.document]]) -> None
             self.app.phase = BuildPhase.WRITING
             for docname, doctree in docs:
                 self.write_doc(docname, doctree)
@@ -623,12 +623,12 @@ class Builder:
         raise NotImplementedError
 
     def write_doc(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         """Where you actually write something to the filesystem."""
         raise NotImplementedError
 
     def write_doc_serialized(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         """Handle parts of write_doc that must be called in the main process
         if parallel build is active.
         """
diff --git a/sphinx/builders/_epub_base.py b/sphinx/builders/_epub_base.py
index 65c9f494c..27f16dee0 100644
--- a/sphinx/builders/_epub_base.py
+++ b/sphinx/builders/_epub_base.py
@@ -232,7 +232,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         self.toc_add_files(self.refnodes)
 
     def toc_add_files(self, refnodes):
-        # type: (List[nodes.Node]) -> None
+        # type: (List[Dict[unicode, Any]]) -> None
         """Add the master_doc, pre and post files to a list of refnodes.
         """
         refnodes.insert(0, {
@@ -260,42 +260,44 @@ class EpubBuilder(StandaloneHTMLBuilder):
         return prefix + fragment.replace(':', '-')
 
     def fix_ids(self, tree):
-        # type: (nodes.Node) -> None
+        # type: (nodes.document) -> None
         """Replace colons with hyphens in href and id attributes.
 
         Some readers crash because they interpret the part as a
         transport protocol specification.
         """
-        for node in tree.traverse(nodes.reference):
-            if 'refuri' in node:
-                m = self.refuri_re.match(node['refuri'])
+        for reference in tree.traverse(nodes.reference):
+            if 'refuri' in reference:
+                m = self.refuri_re.match(reference['refuri'])
                 if m:
-                    node['refuri'] = self.fix_fragment(m.group(1), m.group(2))
-            if 'refid' in node:
-                node['refid'] = self.fix_fragment('', node['refid'])
-        for node in tree.traverse(nodes.target):
-            for i, node_id in enumerate(node['ids']):
+                    reference['refuri'] = self.fix_fragment(m.group(1), m.group(2))
+            if 'refid' in reference:
+                reference['refid'] = self.fix_fragment('', reference['refid'])
+
+        for target in tree.traverse(nodes.target):
+            for i, node_id in enumerate(target['ids']):
                 if ':' in node_id:
-                    node['ids'][i] = self.fix_fragment('', node_id)
+                    target['ids'][i] = self.fix_fragment('', node_id)
 
-            next_node = node.next_node(siblings=True)
+            next_node = target.next_node(siblings=True)
             if next_node and 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)
-        for node in tree.traverse(addnodes.desc_signature):
-            ids = node.attributes['ids']
+
+        for desc_signature in tree.traverse(addnodes.desc_signature):
+            ids = desc_signature.attributes['ids']
             newids = []
             for id in ids:
                 newids.append(self.fix_fragment('', id))
-            node.attributes['ids'] = newids
+            desc_signature.attributes['ids'] = newids
 
     def add_visible_links(self, tree, show_urls='inline'):
-        # type: (nodes.Node, unicode) -> None
+        # type: (nodes.document, unicode) -> None
         """Add visible link targets for external links"""
 
         def make_footnote_ref(doc, label):
-            # type: (nodes.Node, unicode) -> nodes.footnote_reference
+            # type: (nodes.document, unicode) -> nodes.footnote_reference
             """Create a footnote_reference node with children"""
             footnote_ref = nodes.footnote_reference('[#]_')
             footnote_ref.append(nodes.Text(label))
@@ -303,7 +305,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
             return footnote_ref
 
         def make_footnote(doc, label, uri):
-            # type: (nodes.Node, unicode, unicode) -> nodes.footnote
+            # type: (nodes.document, unicode, unicode) -> nodes.footnote
             """Create a footnote node with children"""
             footnote = nodes.footnote(uri)
             para = nodes.paragraph()
@@ -314,7 +316,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
             return footnote
 
         def footnote_spot(tree):
-            # type: (nodes.Node) -> Tuple[nodes.Node, int]
+            # type: (nodes.document) -> Tuple[nodes.Node, int]
             """Find or create a spot to place footnotes.
 
             The function returns the tuple (parent, index)."""
@@ -364,7 +366,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     fn_idx += 1
 
     def write_doc(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         """Write one document file.
 
         This method is overwritten in order to fix fragment identifiers
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index 3e4785044..04c992627 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -24,7 +24,7 @@ from sphinx.util.osutil import make_filename
 
 if False:
     # For type annotation
-    from typing import Any, Dict, Iterable, List, Tuple  # NOQA
+    from typing import Any, Dict, Iterable, List, Set, Tuple  # NOQA
     from docutils import nodes  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.config import Config  # NOQA
@@ -141,7 +141,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
         return metadata
 
     def prepare_writing(self, docnames):
-        # type: (Iterable[unicode]) -> None
+        # type: (Set[unicode]) -> None
         super(Epub3Builder, self).prepare_writing(docnames)
 
         writing_mode = self.config.epub_writing_mode
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index f1c658f7a..aa5c36ac0 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -55,7 +55,7 @@ from sphinx.writers.html import HTMLWriter, HTMLTranslator
 
 if False:
     # For type annotation
-    from typing import Any, Dict, IO, Iterable, Iterator, List, Type, Tuple, Union  # NOQA
+    from typing import Any, Dict, IO, Iterable, Iterator, List, Set, Type, Tuple, Union  # NOQA
     from sphinx.application import Sphinx  # NOQA
     from sphinx.config import Config  # NOQA
     from sphinx.domains import Domain, Index, IndexEntry  # NOQA
@@ -379,8 +379,8 @@ class StandaloneHTMLBuilder(Builder):
         self.script_files.append(JavaScript(filename, **kwargs))
 
     @property
-    def default_translator_class(self):
-        # type: () -> nodes.NodeVisitor
+    def default_translator_class(self):  # type: ignore
+        # type: () -> Type[nodes.NodeVisitor]
         use_html5_writer = self.config.html_experimental_html5_writer
         if use_html5_writer is None:
             use_html5_writer = self.default_html5_translator
@@ -454,7 +454,7 @@ class StandaloneHTMLBuilder(Builder):
         return self.config.html_extra_path + self.config.html_static_path
 
     def render_partial(self, node):
-        # type: (nodes.Nodes) -> Dict[unicode, unicode]
+        # type: (nodes.Node) -> Dict[unicode, unicode]
         """Utility: Render a lone doctree node."""
         if node is None:
             return {'fragment': ''}
@@ -480,7 +480,7 @@ class StandaloneHTMLBuilder(Builder):
         return pub.writer.parts
 
     def prepare_writing(self, docnames):
-        # type: (Iterable[unicode]) -> nodes.Node
+        # type: (Set[unicode]) -> None
         # create the search indexer
         self.indexer = None
         if self.search:
@@ -497,7 +497,7 @@ class StandaloneHTMLBuilder(Builder):
         self.docsettings = OptionParser(
             defaults=self.env.settings,
             components=(self.docwriter,),
-            read_config_files=True).get_default_values()
+            read_config_files=True).get_default_values()  # type: Any
         self.docsettings.compact_lists = bool(self.config.html_compact_lists)
 
         # determine the additional indices to include
@@ -671,7 +671,7 @@ class StandaloneHTMLBuilder(Builder):
         }
 
     def write_doc(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
@@ -1212,7 +1212,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
         return outfilename
 
     def prepare_writing(self, docnames):
-        # type: (Iterable[unicode]) -> None
+        # type: (Set[unicode]) -> None
         super(DirectoryHTMLBuilder, self).prepare_writing(docnames)
         self.globalcontext['no_search_suffix'] = True
 
@@ -1271,7 +1271,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         return self.render_partial(toctree)['fragment']
 
     def assemble_doctree(self):
-        # type: () -> nodes.Node
+        # type: () -> nodes.document
         master = self.config.master_doc
         tree = self.env.get_doctree(master)
         tree = inline_all_toctrees(self, set(), master, tree, darkgreen, [master])
@@ -1354,7 +1354,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         docnames = self.env.all_docs
 
         logger.info(bold(__('preparing documents... ')), nonl=True)
-        self.prepare_writing(docnames)
+        self.prepare_writing(docnames)  # type: ignore
         logger.info(__('done'))
 
         logger.info(bold(__('assembling single document... ')), nonl=True)
diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py
index c6c3e0eb3..ec86740e1 100644
--- a/sphinx/builders/htmlhelp.py
+++ b/sphinx/builders/htmlhelp.py
@@ -221,7 +221,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
         self.build_hhx(self.outdir, self.config.htmlhelp_basename)
 
     def write_doc(self, docname, doctree):
-        # type: (unicode, nodes.Node) -> None
+        # type: (unicode, nodes.document) -> None
         for node in doctree.traverse(nodes.reference):
             # add ``target=_blank`` attributes to external links
             if node.get('internal') is None and 'refuri' in node:
diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py
index 817eab1d7..3010b97bb 100644
--- a/sphinx/builders/latex/__init__.py
+++ b/sphinx/builders/latex/__init__.py
@@ -215,7 +215,7 @@ class LaTeXBuilder(Builder):
         docsettings = OptionParser(
             defaults=self.env.settings,
             components=(docwriter,),
-            read_config_files=True).get_default_values()
+            read_config_files=True).get_default_values()  # type: Any
 
         self.init_document_data()
         self.write_stylesheet()
@@ -245,12 +245,13 @@ class LaTeXBuilder(Builder):
             self.update_doc_context(title, author)
 
             logger.info(__("writing... "), nonl=1)
+            docsettings.author = author
+            docsettings.title = title
+            docsettings.contentsname = self.get_contentsname(docname)
+            docsettings.docname = docname
+            docsettings.docclass = docclass
+
             doctree.settings = docsettings
-            doctree.settings.author = author
-            doctree.settings.title = title
-            doctree.settings.contentsname = self.get_contentsname(docname)
-            doctree.settings.docname = docname
-            doctree.settings.docclass = docclass
             docwriter.write(doctree, destination)
             logger.info("done")
 
@@ -271,7 +272,7 @@ class LaTeXBuilder(Builder):
         self.context['author'] = author
 
     def assemble_doctree(self, indexfile, toctree_only, appendices):
-        # type: (unicode, bool, List[unicode]) -> nodes.Node
+        # type: (unicode, bool, List[unicode]) -> nodes.document
         from docutils import nodes  # NOQA
         self.docnames = set([indexfile] + appendices)
         logger.info(darkgreen(indexfile) + " ", nonl=1)
@@ -303,7 +304,7 @@ class LaTeXBuilder(Builder):
         for pendingnode in largetree.traverse(addnodes.pending_xref):
             docname = pendingnode['refdocname']
             sectname = pendingnode['refsectname']
-            newnodes = [nodes.emphasis(sectname, sectname)]
+            newnodes = [nodes.emphasis(sectname, sectname)]  # type: List[nodes.Node]
             for subdir, title in self.titles:
                 if docname.startswith(subdir):
                     newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
diff --git a/sphinx/builders/latex/transforms.py b/sphinx/builders/latex/transforms.py
index 5a46c17f2..4c3150c68 100644
--- a/sphinx/builders/latex/transforms.py
+++ b/sphinx/builders/latex/transforms.py
@@ -9,6 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+from typing import cast
+
 from docutils import nodes
 
 from sphinx import addnodes
@@ -100,17 +102,17 @@ class ShowUrlsTransform(SphinxTransform):
         return None  # never reached here. only for type hinting
 
     def create_footnote(self, uri, docname):
-        # type: (unicode, unicode) -> Tuple[nodes.footnote, nodes.footnote_ref]
-        label = nodes.label('', '#')
-        para = nodes.paragraph()
-        para.append(nodes.reference('', nodes.Text(uri), refuri=uri, nolinkurl=True))
-        footnote = nodes.footnote(uri, label, para, auto=1, docname=docname)
+        # type: (unicode, unicode) -> Tuple[nodes.footnote, nodes.footnote_reference]
+        reference = nodes.reference('', nodes.Text(uri), refuri=uri, nolinkurl=True)
+        footnote = nodes.footnote(uri, auto=1, docname=docname)
         footnote['names'].append('#')
+        footnote += nodes.label('', '#')
+        footnote += nodes.paragraph('', '', reference)
         self.document.note_autofootnote(footnote)
 
-        label = nodes.Text('#')
-        footnote_ref = nodes.footnote_reference('[#]_', label, auto=1,
+        footnote_ref = nodes.footnote_reference('[#]_', auto=1,
                                                 refid=footnote['ids'][0], docname=docname)
+        footnote_ref += nodes.Text('#')
         self.document.note_autofootnote_ref(footnote_ref)
         footnote.add_backref(footnote_ref['ids'][0])
 
@@ -130,10 +132,10 @@ class ShowUrlsTransform(SphinxTransform):
                     break
 
             # assign new footnote number
-            old_label = footnote[0].astext()
-            footnote[0].replace_self(nodes.label('', str(num)))
+            old_label = cast(nodes.label, footnote[0])
+            old_label.replace_self(nodes.label('', str(num)))
             if old_label in footnote['names']:
-                footnote['names'].remove(old_label)
+                footnote['names'].remove(old_label.astext())
             footnote['names'].append(str(num))
 
             # update footnote_references by new footnote number
@@ -357,11 +359,11 @@ class LaTeXFootnoteTransform(SphinxTransform):
 class LaTeXFootnoteVisitor(nodes.NodeVisitor):
     def __init__(self, document, footnotes):
         # type: (nodes.document, List[nodes.footnote]) -> None
-        self.appeared = set()       # type: Set[Tuple[unicode, nodes.footnote]]
+        self.appeared = set()       # type: Set[Tuple[unicode, unicode]]
         self.footnotes = footnotes  # type: List[nodes.footnote]
-        self.pendings = []          # type: List[nodes.Node]
-        self.table_footnotes = []   # type: List[nodes.Node]
-        self.restricted = None      # type: nodes.Node
+        self.pendings = []          # type: List[nodes.footnote]
+        self.table_footnotes = []   # type: List[nodes.footnote]
+        self.restricted = None      # type: nodes.Element
         super(LaTeXFootnoteVisitor, self).__init__(document)
 
     def unknown_visit(self, node):
@@ -373,12 +375,12 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
         pass
 
     def restrict(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.Element) -> None
         if self.restricted is None:
             self.restricted = node
 
     def unrestrict(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.Element) -> None
         if self.restricted == node:
             self.restricted = None
             pos = node.parent.index(node)
@@ -388,36 +390,36 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
             self.pendings = []
 
     def visit_figure(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.figure) -> None
         self.restrict(node)
 
     def depart_figure(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.figure) -> None
         self.unrestrict(node)
 
     def visit_term(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.term) -> None
         self.restrict(node)
 
     def depart_term(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.term) -> None
         self.unrestrict(node)
 
     def visit_caption(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.caption) -> None
         self.restrict(node)
 
     def depart_caption(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.caption) -> None
         self.unrestrict(node)
 
     def visit_title(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.title) -> None
         if isinstance(node.parent, (nodes.section, nodes.table)):
             self.restrict(node)
 
     def depart_title(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.title) -> None
         if isinstance(node.parent, nodes.section):
             self.unrestrict(node)
         elif isinstance(node.parent, nodes.table):
@@ -426,17 +428,17 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
             self.unrestrict(node)
 
     def visit_thead(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.thead) -> None
         self.restrict(node)
 
     def depart_thead(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.thead) -> None
         self.table_footnotes += self.pendings
         self.pendings = []
         self.unrestrict(node)
 
     def depart_table(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.table) -> None
         tbody = list(node.traverse(nodes.tbody))[0]
         for footnote in reversed(self.table_footnotes):
             fntext = footnotetext('', *footnote.children)
@@ -445,15 +447,15 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
         self.table_footnotes = []
 
     def visit_footnote(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.footnote) -> None
         self.restrict(node)
 
     def depart_footnote(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.footnote) -> None
         self.unrestrict(node)
 
     def visit_footnote_reference(self, node):
-        # type: (nodes.Node) -> None
+        # type: (nodes.footnote_reference) -> None
         number = node.astext().strip()
         docname = node['docname']
         if self.restricted:
@@ -475,7 +477,7 @@ class LaTeXFootnoteVisitor(nodes.NodeVisitor):
         raise nodes.SkipNode
 
     def get_footnote_by_reference(self, node):
-        # type: (nodes.Node) -> nodes.Node
+        # type: (nodes.footnote_reference) -> nodes.footnote
         docname = node['docname']
         for footnote in self.footnotes:
             if docname == footnote['docname'] and footnote['ids'][0] == node['refid']:
diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py
index 13d2f3f44..ca0119465 100644
--- a/sphinx/builders/linkcheck.py
+++ b/sphinx/builders/linkcheck.py
@@ -265,7 +265,7 @@ class CheckExternalLinksBuilder(Builder):
         return self.env.found_docs
 
     def prepare_writing(self, docnames):
-        # type: (nodes.Node) -> None
+        # type: (Set[unicode]) -> None
         return
 
     def write_doc(self, docname, doctree):
diff --git a/sphinx/builders/manpage.py b/sphinx/builders/manpage.py
index 3982c902e..6042c507d 100644
--- a/sphinx/builders/manpage.py
+++ b/sphinx/builders/manpage.py
@@ -67,7 +67,7 @@ class ManualPageBuilder(Builder):
         docsettings = OptionParser(
             defaults=self.env.settings,
             components=(docwriter,),
-            read_config_files=True).get_default_values()
+            read_config_files=True).get_default_values()  # type: Any
 
         logger.info(bold(__('writing... ')), nonl=True)
 
diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py
index f15e0d1ce..f5397ecd6 100644
--- a/sphinx/builders/texinfo.py
+++ b/sphinx/builders/texinfo.py
@@ -124,7 +124,7 @@ class TexinfoBuilder(Builder):
             settings = OptionParser(
                 defaults=self.env.settings,
                 components=(docwriter,),
-                read_config_files=True).get_default_values()
+                read_config_files=True).get_default_values()  # type: Any
             settings.author = author
             settings.title = title
             settings.texinfo_filename = targetname[:-5] + '.info'
@@ -138,7 +138,7 @@ class TexinfoBuilder(Builder):
             logger.info(__("done"))
 
     def assemble_doctree(self, indexfile, toctree_only, appendices):
-        # type: (unicode, bool, List[unicode]) -> nodes.Node
+        # type: (unicode, bool, List[unicode]) -> nodes.document
         self.docnames = set([indexfile] + appendices)
         logger.info(darkgreen(indexfile) + " ", nonl=1)
         tree = self.env.get_doctree(indexfile)
@@ -168,7 +168,7 @@ class TexinfoBuilder(Builder):
         for pendingnode in largetree.traverse(addnodes.pending_xref):
             docname = pendingnode['refdocname']
             sectname = pendingnode['refsectname']
-            newnodes = [nodes.emphasis(sectname, sectname)]
+            newnodes = [nodes.emphasis(sectname, sectname)]  # type: List[nodes.Node]
             for subdir, title in self.titles:
                 if docname.startswith(subdir):
                     newnodes.append(nodes.Text(_(' (in '), _(' (in ')))