From 8201687c5b52a750712d8b6695c36e8e8bf89091 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Thu, 29 Nov 2018 22:18:21 +0900 Subject: [PATCH] Fix annotations for builders --- sphinx/builders/__init__.py | 10 ++--- sphinx/builders/_epub_base.py | 44 ++++++++++---------- sphinx/builders/epub3.py | 4 +- sphinx/builders/html.py | 20 ++++----- sphinx/builders/htmlhelp.py | 2 +- sphinx/builders/latex/__init__.py | 17 ++++---- sphinx/builders/latex/transforms.py | 64 +++++++++++++++-------------- sphinx/builders/linkcheck.py | 2 +- sphinx/builders/manpage.py | 2 +- sphinx/builders/texinfo.py | 6 +-- 10 files changed, 88 insertions(+), 83 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']): - if ':' in node_id: - node['ids'][i] = self.fix_fragment('', node_id) + reference['refuri'] = self.fix_fragment(m.group(1), m.group(2)) + if 'refid' in reference: + reference['refid'] = self.fix_fragment('', reference['refid']) - next_node = node.next_node(siblings=True) + for target in tree.traverse(nodes.target): + for i, node_id in enumerate(target['ids']): + if ':' in node_id: + target['ids'][i] = self.fix_fragment('', node_id) + + 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 ')))