IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #5680 from tk0miya/fix_typehints_for_builders

Browse Source 
Fix annotations for builders
This commit is contained in:
Takeshi KOMIYA 2018-11-29 23:44:57 +09:00 committed by GitHub
commit d8b8ef559e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 88 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
sphinx/builders/__init__.py
View File

@ -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.
"""

44
sphinx/builders/_epub_base.py
View File

@ -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

4
sphinx/builders/epub3.py
View File

@ -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

20
sphinx/builders/html.py
View File

@ -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)

2
sphinx/builders/htmlhelp.py
View File

@ -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:

17
sphinx/builders/latex/__init__.py
View File

@ -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 ')))

64
sphinx/builders/latex/transforms.py
View File

@ -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']:

2
sphinx/builders/linkcheck.py
View File

@ -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):

2
sphinx/builders/manpage.py
View File

@ -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)

6
sphinx/builders/texinfo.py
View File

@ -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 ')))