def build_full_toctree(builder, docname, prune, collapse):
"""Return a single toctree starting from docname containing all
sub-document doctrees.
"""
env = builder.env
doctree = env.get_doctree(env.config.master_doc)
toctrees = []
for toctreenode in doctree.traverse(addnodes.toctree):
toctree = env.resolve_toctree(docname, builder, toctreenode,
collapse=collapse,
prune=prune,
)
toctrees.append(toctree)
if not toctrees:
return None
result = toctrees[0]
for toctree in toctrees[1:]:
if toctree:
result.extend(toctree.children)
env.resolve_references(result, docname, builder)
return result
python类toctree()的实例源码
def init_local_toctree(app):
def _get_local_toctree(docname, **kwds):
doctree = app.env.get_doctree(docname)
if 'maxdepth' not in kwds:
kwds['maxdepth'] = 0
toctrees = []
for toctreenode in doctree.traverse(addnodes.toctree):
toctree = app.env.resolve_toctree(
docname, app.builder, toctreenode, **kwds)
toctrees.append(toctree)
if not toctrees:
return None
result = toctrees[0]
for toctree in toctrees[1:]:
result.extend(toctree.children)
return app.builder.render_partial(result)['fragment']
ctx = app.env.config['html_context']
if 'local_toctree' not in ctx:
ctx['local_toctree'] = _get_local_toctree
def build_full_toctree(builder, docname, prune, collapse):
"""Return a single toctree starting from docname containing all
sub-document doctrees.
"""
env = builder.env
doctree = env.get_doctree(env.config.master_doc)
toctrees = []
for toctreenode in doctree.traverse(addnodes.toctree):
toctree = env.resolve_toctree(docname, builder, toctreenode,
collapse=collapse,
prune=prune,
includehidden=True,
)
if toctree is not None:
toctrees.append(toctree)
if not toctrees:
return None
result = toctrees[0]
for toctree in toctrees[1:]:
if toctree:
result.extend(toctree.children)
env.resolve_references(result, docname, builder)
return result
def build_full_toctree(builder, docname, prune, collapse):
"""Return a single toctree starting from docname containing all
sub-document doctrees.
"""
env = builder.env
doctree = env.get_doctree(env.config.master_doc)
toctrees = []
for toctreenode in doctree.traverse(addnodes.toctree):
toctree = env.resolve_toctree(docname, builder, toctreenode,
collapse=collapse,
prune=prune,
)
toctrees.append(toctree)
if not toctrees:
return None
result = toctrees[0]
for toctree in toctrees[1:]:
if toctree:
result.extend(toctree.children)
env.resolve_references(result, docname, builder)
return result
def get_toctree_for(self, docname, builder, collapse, **kwds):
"""Return the global TOC nodetree."""
doctree = self.get_doctree(self.config.master_doc)
toctrees = []
if 'includehidden' not in kwds:
kwds['includehidden'] = True
if 'maxdepth' not in kwds:
kwds['maxdepth'] = 0
kwds['collapse'] = collapse
for toctreenode in doctree.traverse(addnodes.toctree):
toctree = self.resolve_toctree(docname, builder, toctreenode,
prune=True, **kwds)
if toctree:
toctrees.append(toctree)
if not toctrees:
return None
result = toctrees[0]
for toctree in toctrees[1:]:
result.extend(toctree.children)
return result
def get_and_resolve_doctree(self, docname, builder, doctree=None,
prune_toctrees=True, includehidden=False):
"""Read the doctree from the pickle, resolve cross-references and
toctrees and return it.
"""
if doctree is None:
doctree = self.get_doctree(docname)
# resolve all pending cross-references
self.resolve_references(doctree, docname, builder)
# now, resolve all toctree nodes
for toctreenode in doctree.traverse(addnodes.toctree):
result = self.resolve_toctree(docname, builder, toctreenode,
prune=prune_toctrees,
includehidden=includehidden)
if result is None:
toctreenode.replace_self([])
else:
toctreenode.replace_self(result)
return doctree
def process_autosummary_toc(app, doctree):
"""Insert items described in autosummary:: to the TOC tree, but do
not generate the toctree:: list.
"""
env = app.builder.env
crawled = {}
def crawl_toc(node, depth=1):
crawled[node] = True
for j, subnode in enumerate(node):
try:
if (isinstance(subnode, autosummary_toc) and
isinstance(subnode[0], addnodes.toctree)):
env.note_toctree(env.docname, subnode[0])
continue
except IndexError:
continue
if not isinstance(subnode, nodes.section):
continue
if subnode not in crawled:
crawl_toc(subnode, depth+1)
crawl_toc(doctree)
def get_target_uri(self, docname, typ=None):
#print 'GTU',docname,typ
# FIXME: production lists are not supported yet!
if typ == 'token':
# token references are always inside production lists and must be
# replaced by \token{} in LaTeX
return '@token'
if docname not in self.docnames:
# It can be a 'main' document:
for doc in self.document_data:
if doc[0]==docname:
return "pdf:"+doc[1]+'.pdf'
# It can be in some other document's toctree
for indexname, toctree in self.env.toctree_includes.items():
if docname in toctree:
for doc in self.document_data:
if doc[0]==indexname:
return "pdf:"+doc[1]+'.pdf'
# No idea
raise NoUri
else: # Local link
return ""
def html_page_context(app, pagename, templatename, context, doctree):
"""Event handler for the html-page-context signal.
Modifies the context directly.
- Replaces the 'toc' value created by the HTML builder with one
that shows all document titles and the local table of contents.
- Sets display_toc to True so the table of contents is always
displayed, even on empty pages.
- Replaces the 'toctree' function with one that uses the entire
document structure, ignores the maxdepth argument, and uses
only prune and collapse.
"""
rendered_toc = get_rendered_toctree(app.builder, pagename)
context['toc'] = rendered_toc
context['display_toc'] = True # force toctree to display
if "toctree" not in context:
# json builder doesn't use toctree func, so nothing to replace
return
def make_toctree(collapse=True):
return get_rendered_toctree(app.builder,
pagename,
prune=False,
collapse=collapse,
)
context['toctree'] = make_toctree
def get_rendered_toctree(builder, docname, prune=False, collapse=True):
"""Build the toctree relative to the named document,
with the given parameters, and then return the rendered
HTML fragment.
"""
fulltoc = build_full_toctree(builder,
docname,
prune=prune,
collapse=collapse,
)
rendered_toc = builder.render_partial(fulltoc)['fragment']
return rendered_toc
def html_page_context(app, pagename, templatename, context, doctree):
"""Event handler for the html-page-context signal.
Modifies the context directly.
- Replaces the 'toc' value created by the HTML builder with one
that shows all document titles and the local table of contents.
- Sets display_toc to True so the table of contents is always
displayed, even on empty pages.
- Replaces the 'toctree' function with one that uses the entire
document structure, ignores the maxdepth argument, and uses
only prune and collapse.
"""
rendered_toc = get_rendered_toctree(app.builder, pagename)
context['toc_full'] = rendered_toc
context['display_toc'] = True # force toctree to display
if "toctree" not in context:
# json builder doesn't use toctree func, so nothing to replace
return
def make_toctree(collapse=True, maxdepth=-1, includehidden=True):
return get_rendered_toctree(app.builder,
pagename,
prune=False,
collapse=collapse,
)
context['toctree'] = make_toctree
def get_rendered_toctree(builder, docname, prune=False, collapse=True):
"""Build the toctree relative to the named document,
with the given parameters, and then return the rendered
HTML fragment.
"""
fulltoc = build_full_toctree(builder,
docname,
prune=prune,
collapse=collapse,
)
rendered_toc = builder.render_partial(fulltoc)['fragment']
return rendered_toc
def _sort_docnames(self, docname, traversed):
tree = self.env.get_doctree(docname)
for toctreenode in tree.traverse(addnodes.toctree):
includefiles = map(str, toctreenode['includefiles'])
for includefile in includefiles:
if includefile not in traversed:
try:
traversed.append(includefile)
self._sort_docnames(includefile, traversed)
except Exception:
pass
def register_parents(self, ordered_docnames, docname):
ordered_docnames.append(docname)
doctree = self.env.get_doctree(docname)
for node in doctree.traverse(addnodes.toctree):
for includefile in node['includefiles']:
ConfluenceState.registerParentDocname(includefile, docname)
self.register_parents(ordered_docnames, includefile)
def test_empty():
"""Local TOC is showing, as toctree was empty"""
for (app, status, warning) in build_all('test-empty'):
assert app.env.get_doctree('index').traverse(addnodes.toctree)
content = open(os.path.join(app.outdir, 'index.html')).read()
if sphinx.version_info < (1, 4):
if isinstance(app.builder, SingleFileHTMLBuilder):
assert '<div class="toctree-wrapper compound">\n</div>' in content
assert '<div class="local-toc">' in content
else:
global_toc = (
'<div class="toctree-wrapper compound">\n'
'<ul class="simple">\n</ul>\n'
'</div>'
)
local_toc = (
'<div class="local-toc"><ul class="simple">'
'</ul>\n</div>'
)
assert global_toc in content
assert local_toc not in content
else:
global_toc = '<div class="toctree-wrapper compound">\n</div>'
local_toc = (
'<div class="local-toc"><ul>\n'
'<li><a class="reference internal" href="#">test-empty</a></li>'
'</ul>\n</div>'
)
assert global_toc in content
assert local_toc not in content
def test_missing_toctree():
"""Local TOC is showing, as toctree was missing"""
for (app, status, warning) in build_all('test-missing-toctree'):
assert app.env.get_doctree('index').traverse(addnodes.toctree) == []
content = open(os.path.join(app.outdir, 'index.html')).read()
assert '<div class="toctree' not in content
assert '<div class="local-toc">' in content
def process_doc(self, env, docname, document):
labels, anonlabels = self.data['labels'], self.data['anonlabels']
for name, explicit in iteritems(document.nametypes):
if not explicit:
continue
labelid = document.nameids[name]
if labelid is None:
continue
node = document.ids[labelid]
if node.tagname == 'target' and 'refid' in node: # indirect hyperlink targets
node = document.ids.get(node['refid'])
labelid = node['names'][0]
if name.isdigit() or 'refuri' in node or \
node.tagname.startswith('desc_'):
# ignore footnote labels, labels automatically generated from a
# link and object descriptions
continue
if name in labels:
env.warn_node('duplicate label %s, ' % name + 'other instance '
'in ' + env.doc2path(labels[name][0]), node)
anonlabels[name] = docname, labelid
if node.tagname == 'section':
sectname = clean_astext(node[0]) # node[0] == title node
elif self.is_enumerable_node(node):
sectname = self.get_numfig_title(node)
if not sectname:
continue
elif node.traverse(addnodes.toctree):
n = node.traverse(addnodes.toctree)[0]
if n.get('caption'):
sectname = n['caption']
else:
continue
else:
# anonymous-only labels
continue
labels[name] = docname, labelid, sectname
def html_page_context(app, pagename, templatename, context, doctree):
"""Event handler for the html-page-context signal.
Modifies the context directly.
- Replaces the 'toc' value created by the HTML builder with one
that shows all document titles and the local table of contents.
- Sets display_toc to True so the table of contents is always
displayed, even on empty pages.
- Replaces the 'toctree' function with one that uses the entire
document structure, ignores the maxdepth argument, and uses
only prune and collapse.
"""
rendered_toc = get_rendered_toctree(app.builder, pagename)
context['toc'] = rendered_toc
context['display_toc'] = True # force toctree to display
if "toctree" not in context:
# json builder doesn't use toctree func, so nothing to replace
return
def make_toctree(collapse=True):
return get_rendered_toctree(app.builder,
pagename,
prune=False,
collapse=collapse,
)
context['toctree'] = make_toctree
def get_rendered_toctree(builder, docname, prune=False, collapse=True):
"""Build the toctree relative to the named document,
with the given parameters, and then return the rendered
HTML fragment.
"""
fulltoc = build_full_toctree(builder,
docname,
prune=prune,
collapse=collapse,
)
rendered_toc = builder.render_partial(fulltoc)['fragment']
return rendered_toc
def on_doctree_read(app, doctree):
# Remove TOC entry (see: https://gist.github.com/kakawait/9215487)
for toctreenode in doctree.traverse(addnodes.toctree):
for e in toctreenode['entries']:
ref = str(e[1])
if ref in SKIP_DOCUMENTS:
toctreenode['entries'].remove(e)
def collect_relations(self):
traversed = set()
def traverse_toctree(parent, docname):
# traverse toctree by pre-order
yield parent, docname
traversed.add(docname)
for child in (self.toctree_includes.get(docname) or []):
for subparent, subdocname in traverse_toctree(docname, child):
if subdocname not in traversed:
yield subparent, subdocname
traversed.add(subdocname)
relations = {}
docnames = traverse_toctree(None, self.config.master_doc)
prevdoc = None
parent, docname = next(docnames)
for nextparent, nextdoc in docnames:
relations[docname] = [parent, prevdoc, nextdoc]
prevdoc = docname
docname = nextdoc
parent = nextparent
relations[docname] = [parent, prevdoc, None]
return relations
def check_consistency(self):
"""Do consistency checks."""
for docname in sorted(self.all_docs):
if docname not in self.files_to_rebuild:
if docname == self.config.master_doc:
# the master file is not included anywhere ;)
continue
if 'orphan' in self.metadata[docname]:
continue
self.warn(docname, 'document isn\'t included in any toctree')
def autosummary_toc_visit_html(self, node):
"""Hide autosummary toctree list in HTML output."""
raise nodes.SkipNode
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = Options()
self.warnings = []
self.result = ViewList()
names = [x.strip().split()[0] for x in self.content
if x.strip() and re.search(r'^[~a-zA-Z_]', x.strip()[0])]
items = self.get_items(names)
nodes = self.get_table(items)
if 'toctree' in self.options:
dirname = posixpath.dirname(env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
for name, sig, summary, real_name in items:
docname = posixpath.join(tree_prefix, real_name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
self.warn('toctree references unknown document %r'
% docname)
docnames.append(docname)
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docn) for docn in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
nodes.append(tocnode)
return self.warnings + nodes
def assemble_doctree(self, indexfile, toctree_only, appendices):
self.docnames = set([indexfile] + appendices)
self.info(darkgreen(indexfile) + " ", nonl=1)
tree = self.env.get_doctree(indexfile)
tree['docname'] = indexfile
if toctree_only:
# extract toctree nodes from the tree and put them in a
# fresh document
new_tree = new_document('<texinfo output>')
new_sect = nodes.section()
new_sect += nodes.title(u'<Set title in conf.py>',
u'<Set title in conf.py>')
new_tree += new_sect
for node in tree.traverse(addnodes.toctree):
new_sect += node
tree = new_tree
largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
darkgreen, [indexfile])
largetree['docname'] = indexfile
for docname in appendices:
appendix = self.env.get_doctree(docname)
appendix['docname'] = docname
largetree.append(appendix)
self.info()
self.info("resolving references...")
self.env.resolve_references(largetree, indexfile, self)
# TODO: add support for external :ref:s
for pendingnode in largetree.traverse(addnodes.pending_xref):
docname = pendingnode['refdocname']
sectname = pendingnode['refsectname']
newnodes = [nodes.emphasis(sectname, sectname)]
for subdir, title in self.titles:
if docname.startswith(subdir):
newnodes.append(nodes.Text(_(' (in '), _(' (in ')))
newnodes.append(nodes.emphasis(title, title))
newnodes.append(nodes.Text(')', ')'))
break
else:
pass
pendingnode.replace_self(newnodes)
return largetree
def write(self, *ignored):
docwriter = LaTeXWriter(self)
docsettings = OptionParser(
defaults=self.env.settings,
components=(docwriter,),
read_config_files=True).get_default_values()
self.init_document_data()
for entry in self.document_data:
docname, targetname, title, author, docclass = entry[:5]
toctree_only = False
if len(entry) > 5:
toctree_only = entry[5]
destination = FileOutput(
destination_path=path.join(self.outdir, targetname),
encoding='utf-8')
self.info("processing " + targetname + "... ", nonl=1)
toctrees = self.env.get_doctree(docname).traverse(addnodes.toctree)
if toctrees:
if toctrees[0].get('maxdepth') > 0:
tocdepth = toctrees[0].get('maxdepth')
else:
tocdepth = None
else:
tocdepth = None
doctree = self.assemble_doctree(
docname, toctree_only,
appendices=((docclass != 'howto') and self.config.latex_appendices or []))
doctree['tocdepth'] = tocdepth
self.post_process_images(doctree)
self.info("writing... ", nonl=1)
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)
self.info("done")
def get_contentsname(self, indexfile):
tree = self.env.get_doctree(indexfile)
contentsname = None
for toctree in tree.traverse(addnodes.toctree):
if toctree['caption']:
contentsname = toctree['caption']
break
return contentsname
def inline_all_toctrees(builder, docnameset, docname, tree, colorfunc, traversed):
"""Inline all toctrees in the *tree*.
Record all docnames in *docnameset*, and output docnames with *colorfunc*.
"""
tree = tree.deepcopy()
for toctreenode in tree.traverse(addnodes.toctree):
newnodes = []
includefiles = map(text_type, toctreenode['includefiles'])
for includefile in includefiles:
if includefile not in traversed:
try:
traversed.append(includefile)
builder.info(colorfunc(includefile) + " ", nonl=1)
subtree = inline_all_toctrees(builder, docnameset, includefile,
builder.env.get_doctree(includefile),
colorfunc, traversed)
docnameset.add(includefile)
except Exception:
builder.warn('toctree contains ref to nonexisting '
'file %r' % includefile,
builder.env.doc2path(docname))
else:
sof = addnodes.start_of_file(docname=includefile)
sof.children = subtree.children
for sectionnode in sof.traverse(nodes.section):
if 'docname' not in sectionnode:
sectionnode['docname'] = includefile
newnodes.append(sof)
toctreenode.parent.replace(toctreenode, newnodes)
return tree
def test_empty():
"""Local TOC is showing, as toctree was empty"""
for (app, status, warning) in build_all('test-empty'):
assert app.env.get_doctree('index').traverse(addnodes.toctree)
content = open(os.path.join(app.outdir, 'index.html')).read()
if sphinx.version_info < (1, 4):
if isinstance(app.builder, SingleFileHTMLBuilder):
assert '<div class="toctree-wrapper compound">\n</div>' in content
assert '<div class="local-toc">' in content
else:
global_toc = (
'<div class="toctree-wrapper compound">\n'
'<ul class="simple">\n</ul>\n'
'</div>'
)
local_toc = (
'<div class="local-toc"><ul class="simple">'
'</ul>\n</div>'
)
assert global_toc in content
assert local_toc not in content
else:
global_toc = '<div class="toctree-wrapper compound">\n</div>'
local_toc = (
'<div class="local-toc"><ul>\n'
'<li><a class="reference internal" href="#">test-empty</a></li>'
'</ul>\n</div>'
)
assert global_toc in content
assert local_toc not in content
def test_missing_toctree():
"""Local TOC is showing, as toctree was missing"""
for (app, status, warning) in build_all('test-missing-toctree'):
assert app.env.get_doctree('index').traverse(addnodes.toctree) == []
content = open(os.path.join(app.outdir, 'index.html')).read()
assert '<div class="toctree' not in content
assert '<div class="local-toc">' in content
