diff --git a/sphinx/environment/adapters/toctree.py b/sphinx/environment/adapters/toctree.py index fe7bd3d0d0..d5f827ddec 100644 --- a/sphinx/environment/adapters/toctree.py +++ b/sphinx/environment/adapters/toctree.py @@ -8,9 +8,11 @@ :license: BSD, see LICENSE for details. """ -from typing import Iterable, cast +from typing import cast +from typing import Iterable, List from docutils import nodes +from docutils.nodes import Element, Node from sphinx import addnodes from sphinx.locale import __ @@ -20,20 +22,18 @@ from sphinx.util.nodes import clean_astext, process_only_nodes if False: # For type annotation - from typing import Any, Dict, List # NOQA - from sphinx.builders import Builder # NOQA - from sphinx.environment import BuildEnvironment # NOQA + from sphinx.builders import Builder + from sphinx.environment import BuildEnvironment + logger = logging.getLogger(__name__) class TocTree: - def __init__(self, env): - # type: (BuildEnvironment) -> None + def __init__(self, env: "BuildEnvironment") -> None: self.env = env - def note(self, docname, toctreenode): - # type: (str, addnodes.toctree) -> None + def note(self, docname: str, toctreenode: addnodes.toctree) -> None: """Note a TOC tree directive in a document and gather information about file relations from it. """ @@ -48,9 +48,9 @@ class TocTree: self.env.files_to_rebuild.setdefault(includefile, set()).add(docname) self.env.toctree_includes.setdefault(docname, []).extend(includefiles) - def resolve(self, docname, builder, toctree, prune=True, maxdepth=0, - titles_only=False, collapse=False, includehidden=False): - # type: (str, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Element + def resolve(self, docname: str, builder: "Builder", toctree: addnodes.toctree, + prune: bool = True, maxdepth: int = 0, titles_only: bool = False, + collapse: bool = False, includehidden: bool = False) -> Element: """Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or a new node. @@ -86,8 +86,7 @@ class TocTree: toctree_ancestors = self.get_toctree_ancestors(docname) excluded = Matcher(self.env.config.exclude_patterns) - def _toctree_add_classes(node, depth): - # type: (nodes.Element, int) -> None + def _toctree_add_classes(node: Element, depth: int) -> None: """Add 'toctree-l%d' and 'current' classes to the toctree.""" for subnode in node.children: if isinstance(subnode, (addnodes.compact_paragraph, @@ -105,7 +104,7 @@ class TocTree: if not subnode['anchorname']: # give the whole branch a 'current' class # (useful for styling it differently) - branchnode = subnode # type: nodes.Element + branchnode = subnode # type: Element while branchnode: branchnode['classes'].append('current') branchnode = branchnode.parent @@ -117,11 +116,12 @@ class TocTree: subnode['iscurrent'] = True subnode = subnode.parent - def _entries_from_toctree(toctreenode, parents, separate=False, subtree=False): - # type: (addnodes.toctree, List[str], bool, bool) -> List[nodes.Element] + def _entries_from_toctree(toctreenode: addnodes.toctree, parents: List[str], + separate: bool = False, subtree: bool = False + ) -> List[Element]: """Return TOC entries for a toctree node.""" refs = [(e[0], e[1]) for e in toctreenode['entries']] - entries = [] # type: List[nodes.Element] + entries = [] # type: List[Element] for (title, ref) in refs: try: refdoc = None @@ -265,8 +265,7 @@ class TocTree: docname, refnode['refuri']) + refnode['anchorname'] return newnode - def get_toctree_ancestors(self, docname): - # type: (str) -> List[str] + def get_toctree_ancestors(self, docname: str) -> List[str]: parent = {} for p, children in self.env.toctree_includes.items(): for child in children: @@ -278,8 +277,8 @@ class TocTree: d = parent[d] return ancestors - def _toctree_prune(self, node, depth, maxdepth, collapse=False): - # type: (nodes.Element, int, int, bool) -> None + def _toctree_prune(self, node: Element, depth: int, maxdepth: int, collapse: bool = False + ) -> None: """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: if isinstance(subnode, (addnodes.compact_paragraph, @@ -300,8 +299,7 @@ class TocTree: # recurse on visible children self._toctree_prune(subnode, depth + 1, maxdepth, collapse) - def get_toc_for(self, docname, builder): - # type: (str, Builder) -> nodes.Node + def get_toc_for(self, docname: str, builder: "Builder") -> Node: """Return a TOC nodetree -- for use on the same page only!""" tocdepth = self.env.metadata[docname].get('tocdepth', 0) try: @@ -316,11 +314,11 @@ class TocTree: node['refuri'] = node['anchorname'] or '#' return toc - def get_toctree_for(self, docname, builder, collapse, **kwds): - # type: (str, Builder, bool, Any) -> nodes.Element + def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool, **kwds + ) -> Element: """Return the global TOC nodetree.""" doctree = self.env.get_doctree(self.env.config.master_doc) - toctrees = [] # type: List[nodes.Element] + toctrees = [] # type: List[Element] if 'includehidden' not in kwds: kwds['includehidden'] = True if 'maxdepth' not in kwds: