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

Fix annotations for toctree

Browse Source
This commit is contained in:
Takeshi KOMIYA 2018-12-10 09:57:21 +09:00
parent 63af636fd9
commit fd47f3baf7
1 changed files with 19 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
sphinx/environment/adapters/toctree.py
View File

@ -9,6 +9,8 @@
:license: BSD, see LICENSE for details. :license: BSD, see LICENSE for details.
""" """
from typing import Iterable, cast
from docutils import nodes from docutils import nodes
from sphinx import addnodes from sphinx import addnodes
@ -50,7 +52,7 @@ class TocTree:
def resolve(self, docname, builder, toctree, prune=True, maxdepth=0, def resolve(self, docname, builder, toctree, prune=True, maxdepth=0,
titles_only=False, collapse=False, includehidden=False): titles_only=False, collapse=False, includehidden=False):
# type: (unicode, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Node # type: (unicode, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Element # NOQA
"""Resolve a *toctree* node into individual bullet lists with titles """Resolve a *toctree* node into individual bullet lists with titles
as items, returning None (if no containing titles are found) or as items, returning None (if no containing titles are found) or
a new node. a new node.
@ -118,10 +120,10 @@ class TocTree:
subnode = subnode.parent subnode = subnode.parent
def _entries_from_toctree(toctreenode, parents, separate=False, subtree=False): def _entries_from_toctree(toctreenode, parents, separate=False, subtree=False):
# type: (addnodes.toctree, List[nodes.Node], bool, bool) -> List[nodes.Node] # type: (addnodes.toctree, List[unicode], bool, bool) -> List[nodes.Element]
"""Return TOC entries for a toctree node.""" """Return TOC entries for a toctree node."""
refs = [(e[0], e[1]) for e in toctreenode['entries']] refs = [(e[0], e[1]) for e in toctreenode['entries']]
entries = [] entries = [] # type: List[nodes.Element]
for (title, ref) in refs: for (title, ref) in refs:
try: try:
refdoc = None refdoc = None
@ -184,9 +186,15 @@ class TocTree:
# if titles_only is given, only keep the main title and # if titles_only is given, only keep the main title and
# sub-toctrees # sub-toctrees
if titles_only: if titles_only:
# children of toc are:
# - list_item + compact_paragraph + (reference and subtoc)
# - only + subtoc
# - toctree
children = cast(Iterable[nodes.Element], toc)
# delete everything but the toplevel title(s) # delete everything but the toplevel title(s)
# and toctrees # and toctrees
for toplevel in toc: for toplevel in children:
# nodes with length 1 don't have any children anyway # nodes with length 1 don't have any children anyway
if len(toplevel) > 1: if len(toplevel) > 1:
subtrees = toplevel.traverse(addnodes.toctree) subtrees = toplevel.traverse(addnodes.toctree)
@ -199,16 +207,17 @@ class TocTree:
if not (subtocnode.get('hidden', False) and if not (subtocnode.get('hidden', False) and
not includehidden): not includehidden):
i = subtocnode.parent.index(subtocnode) + 1 i = subtocnode.parent.index(subtocnode) + 1
for item in _entries_from_toctree( for entry in _entries_from_toctree(
subtocnode, [refdoc] + parents, subtocnode, [refdoc] + parents,
subtree=True): subtree=True):
subtocnode.parent.insert(i, item) subtocnode.parent.insert(i, entry)
i += 1 i += 1
subtocnode.parent.remove(subtocnode) subtocnode.parent.remove(subtocnode)
if separate: if separate:
entries.append(toc) entries.append(toc)
else: else:
entries.extend(toc.children) children = cast(Iterable[nodes.Element], toc)
entries.extend(children)
if not subtree and not separate: if not subtree and not separate:
ret = nodes.bullet_list() ret = nodes.bullet_list()
ret += entries ret += entries
@ -247,7 +256,7 @@ class TocTree:
_toctree_add_classes(newnode, 1) _toctree_add_classes(newnode, 1)
self._toctree_prune(newnode, 1, prune and maxdepth or 0, collapse) self._toctree_prune(newnode, 1, prune and maxdepth or 0, collapse)
if len(newnode[-1]) == 0: # No titles found if isinstance(newnode[-1], nodes.Element) and len(newnode[-1]) == 0: # No titles found
return None return None
# set the target paths in the toctrees (they are not known at TOC # set the target paths in the toctrees (they are not known at TOC
@ -310,10 +319,10 @@ class TocTree:
return toc return toc
def get_toctree_for(self, docname, builder, collapse, **kwds): def get_toctree_for(self, docname, builder, collapse, **kwds):
# type: (unicode, Builder, bool, Any) -> nodes.Node # type: (unicode, Builder, bool, Any) -> nodes.Element
"""Return the global TOC nodetree.""" """Return the global TOC nodetree."""
doctree = self.env.get_doctree(self.env.config.master_doc) doctree = self.env.get_doctree(self.env.config.master_doc)
toctrees = [] # type: List[addnodes.toctree] toctrees = [] # type: List[nodes.Element]
if 'includehidden' not in kwds: if 'includehidden' not in kwds:
kwds['includehidden'] = True kwds['includehidden'] = True
if 'maxdepth' not in kwds: if 'maxdepth' not in kwds: