def run(self):
env = self.state.document.settings.env
mapper = env.autoapi_mapper
objects = [mapper.all_objects[name] for name in self._get_names()]
nodes_ = self._get_table(objects)
if "toctree" in self.options:
dirname = posixpath.dirname(env.docname)
tree_prefix = self.options["toctree"].strip()
docnames = []
for obj in objects:
docname = posixpath.join(tree_prefix, obj.name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
self.reporter.warning(
"toctree references unknown document {}".format(
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 = sphinx.ext.autosummary.autosummary_toc("", "", tocnode)
nodes_.append(tocnode)
return nodes_
def run(self):
self.warnings = []
env = self.state.document.settings.env
mapper = env.autoapi_mapper
objects = [mapper.all_objects[name] for name in self._get_names()]
nodes_ = self._get_table(objects)
if 'toctree' in self.options:
dirname = posixpath.dirname(env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
for obj in objects:
docname = posixpath.join(tree_prefix, obj.name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
self.warn('toctree references unknown document {}'.format(
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 = sphinx.ext.autosummary.autosummary_toc('', '', tocnode)
nodes_.append(tocnode)
return self.warnings + nodes_
def toctree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
env = state.document.settings.env
suffix = env.config.source_suffix
dirname = posixpath.dirname(env.docname)
ret = []
subnode = addnodes.toctree()
includefiles = []
includetitles = {}
for docname in content:
if not docname:
continue
# look for explicit titles and documents ("Some Title <document>").
m = caption_ref_re.match(docname)
if m:
docname = m.group(2)
includetitles[docname] = m.group(1)
# absolutize filenames, remove suffixes
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
ret.append(
state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=lineno))
else:
includefiles.append(docname)
subnode['includefiles'] = includefiles
subnode['includetitles'] = includetitles
subnode['maxdepth'] = options.get('maxdepth', -1)
ret.append(subnode)
return ret
def run(self):
# type: () -> List[nodes.Node]
self.env = env = self.state.document.settings.env
self.genopt = Options()
self.warnings = [] # type: List[nodes.Node]
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 run(self):
self.warnings = []
env = self.state.document.settings.env
mapper = env.autoapi_mapper
objects = [mapper.all_objects[name] for name in self._get_names()]
nodes_ = self._get_table(objects)
if "toctree" in self.options:
dirname = posixpath.dirname(env.docname)
tree_prefix = self.options["toctree"].strip()
docnames = []
for obj in objects:
docname = posixpath.join(tree_prefix, obj.name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
self.warn("toctree references unknown document {}".format(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 = sphinx.ext.autosummary.autosummary_toc("", "", tocnode)
nodes_.append(tocnode)
return self.warnings + nodes_
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.warnings = []
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:
suffix = env.config.source_suffix
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, docname) for docname in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
nodes.append(tocnode)
return self.warnings + nodes
def run(self):
# type: () -> List[nodes.Node]
self.genopt = Options()
self.warnings = [] # type: List[nodes.Node]
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(self.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 self.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 run(self):
# type: () -> List[nodes.Node]
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno)
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(self.env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
excluded = Matcher(self.config.exclude_patterns)
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 self.env.found_docs:
if excluded(self.env.doc2path(docname, None)):
logger.warning(__('toctree references excluded document %r'), docname)
else:
logger.warning(__('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
nodes.append(autosummary_toc('', '', tocnode))
return nodes
def toctree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
env = state.document.settings.env
suffix = env.config.source_suffix
dirname = posixpath.dirname(env.docname)
ret = []
subnode = addnodes.toctree()
includefiles = []
includetitles = {}
for docname in content:
if not docname:
continue
# look for explicit titles and documents ("Some Title <document>").
m = caption_ref_re.match(docname)
if m:
docname = m.group(2)
includetitles[docname] = m.group(1)
# absolutize filenames, remove suffixes
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
ret.append(state.document.reporter.warning(
'toctree references unknown document %r' % docname, line=lineno))
else:
includefiles.append(docname)
subnode['includefiles'] = includefiles
subnode['includetitles'] = includetitles
subnode['maxdepth'] = options.get('maxdepth', -1)
ret.append(subnode)
return ret
def run(self) -> List[Node]:
subnode = addnodes.toctree()
subnode['parent'] = self.env.docname
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
subnode['entries'] = []
subnode['includefiles'] = []
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = 'glob' in self.options
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['alpha'] = self.options.get('alpha', 0)
subnode['continue'] = self.options.get('continue', 1)
subnode['titlesonly'] = 'titlesonly' in self.options
self.set_source_info(subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret = self.parse_content(subnode)
ret.append(wrappernode)
return ret
def run(self) -> List[Node]:
toc_tree_node = addnodes.toctree(
entries=[('', mentioned_doc)
for mentioned_doc in mentioned_docs],
glob=False,
includefiles=[],
)
return [toc_tree_node]
def run(self) -> List[Node]:
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno, self.state)
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(self.env.docname)
tree_prefix = self.options["toctree"].strip()
docnames = []
excluded = Matcher(self.config.exclude_patterns)
filename_map = self.config.autosummary_filename_map
for name, sig, summary, real_name, _ in items:
real_name = filename_map.get(real_name, real_name)
docname = posixpath.join(tree_prefix, real_name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in self.env.found_docs:
if excluded(self.env.doc2path(docname, None)):
msg = __(
"autosummary references excluded document %r. Ignored."
)
else:
msg = __("autosummary: stub file not found %r. "
"Check your autosummary_generate setting.")
logger.warning(msg,
real_name,
location=self.get_source_info())
continue
docnames.append(docname)
if docnames:
tocnode = addnodes.toctree()
tocnode["includefiles"] = docnames
tocnode["entries"] = [(None, docn) for docn in docnames]
tocnode["maxdepth"] = -1
tocnode["glob"] = None
tocnode["caption"] = self.options.get("caption")
nodes.append(autosummary_toc("", "", tocnode))
if "toctree" not in self.options and "caption" in self.options:
logger.warning(
__("A captioned autosummary requires :toctree: option. ignored."
),
location=nodes[-1],
)
return nodes
def create_toc(names, maxdepth=-1):
"""Create toc node entries for names.
"""
tocnode = addnodes.toctree()
tocnode['includefiles'] = [name for _short_name, name in names]
tocnode['entries'] = [(short_name, name) for short_name, name in names]
tocnode['maxdepth'] = maxdepth
tocnode['glob'] = None
return tocnode
def toctree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
env = state.document.settings.env
suffix = env.config.source_suffix
dirname = posixpath.dirname(env.docname)
glob = 'glob' in options
ret = []
subnode = addnodes.toctree()
includefiles = []
includetitles = {}
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in content:
if not entry:
continue
if not glob:
# look for explicit titles and documents ("Some Title <document>").
m = caption_ref_re.match(entry)
if m:
docname = m.group(2)
includetitles[docname] = m.group(1)
else:
docname = entry
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
ret.append(
state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=lineno))
else:
includefiles.append(docname)
else:
patname = posixpath.normpath(posixpath.join(dirname, entry))
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
includefiles.append(docname)
if not docnames:
ret.append(
state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents' %
entry,
line=lineno))
subnode['includefiles'] = includefiles
subnode['includetitles'] = includetitles
subnode['maxdepth'] = options.get('maxdepth', -1)
subnode['glob'] = glob
ret.append(subnode)
return ret
def run(self) -> List[Node]:
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno, self.state)
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(self.env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
excluded = Matcher(self.config.exclude_patterns)
filename_map = self.config.autosummary_filename_map
for _name, _sig, _summary, real_name in items:
real_name = filename_map.get(real_name, real_name)
docname = posixpath.join(tree_prefix, real_name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in self.env.found_docs:
if excluded(self.env.doc2path(docname, False)):
msg = __(
'autosummary references excluded document %r. Ignored.'
)
else:
msg = __('autosummary: stub file not found %r. '
'Check your autosummary_generate setting.')
logger.warning(msg,
real_name,
location=self.get_location())
continue
docnames.append(docname)
if docnames:
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docn) for docn in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode['caption'] = self.options.get('caption')
nodes.append(autosummary_toc('', '', tocnode))
if 'toctree' not in self.options and 'caption' in self.options:
logger.warning(__(
'A captioned autosummary requires :toctree: option. ignored.'),
location=nodes[-1])
return nodes
def toctree_directive(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
env = state.document.settings.env
suffix = env.config.source_suffix
dirname = posixpath.dirname(env.docname)
glob = 'glob' in options
ret = []
subnode = addnodes.toctree()
includefiles = []
includetitles = {}
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in content:
if not entry:
continue
if not glob:
# look for explicit titles and documents ("Some Title <document>").
m = caption_ref_re.match(entry)
if m:
docname = m.group(2)
includetitles[docname] = m.group(1)
else:
docname = entry
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
ret.append(state.document.reporter.warning(
'toctree references unknown document %r' % docname, line=lineno))
else:
includefiles.append(docname)
else:
patname = posixpath.normpath(posixpath.join(dirname, entry))
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
includefiles.append(docname)
if not docnames:
ret.append(state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents' % entry,
line=lineno))
subnode['includefiles'] = includefiles
subnode['includetitles'] = includetitles
subnode['maxdepth'] = options.get('maxdepth', -1)
subnode['glob'] = glob
ret.append(subnode)
return ret
def run(self) -> List[Node]:
nodes = [] # TODO: generate table
docnames = ['fibre_types/' + self.arguments[0].replace('.', '_')]
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docn) for docn in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode['caption'] = self.options.get('caption')
nodes.append(fibresummary_toc('', '', tocnode))
return nodes
def run(self):
doc = self.state.document
env = doc.settings.env
output = []
entries = []
includefiles = []
glob_regex = 'glob-regex' in self.options
glob = glob_regex or 'glob' in self.options
if glob:
content_iter = self._glob_content(env, self.content, glob_regex)
else:
content_iter = self.content
for entry in content_iter:
if not entry:
continue
docname = docname_join(env.docname, entry)
if docname not in env.found_docs:
output.append(
doc.reporter.warning(
'feed contains a reference to nonexisting '
'document %r' % docname,
line=self.lineno))
env.note_reread()
else:
entries.append((None, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
subnode['entries'] = entries
subnode['includefiles'] = includefiles
subnode['maxdepth'] = 1
subnode['glob'] = False
subnode['hidden'] = True
subnode['numbered'] = False
subnode['titlesonly'] = False
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
output.append(wrappernode)
subnode = feed()
subnode['entries'] = includefiles
subnode['rss'] = self.options.get('rss')
subnode['title'] = self.options.get('title', '')
subnode['link'] = self.options.get('link', '')
subnode['description'] = self.options.get('description', '')
output.append(subnode)
return output
def run(self):
# type: () -> List[nodes.Node]
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno, self.state)
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(self.env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
excluded = Matcher(self.config.exclude_patterns)
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 self.env.found_docs:
location = self.state_machine.get_source_and_line(
self.lineno)
if excluded(self.env.doc2path(docname, None)):
msg = __(
'autosummary references excluded document %r. Ignored.'
)
else:
msg = __('autosummary: stub file not found %r. '
'Check your autosummary_generate setting.')
logger.warning(msg, real_name, location=location)
continue
docnames.append(docname)
if docnames:
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docn) for docn in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
nodes.append(autosummary_toc('', '', tocnode))
return nodes
def _process_asdf_toctree(self, standard_prefix):
links = []
for name in self.content:
if not name:
continue
schema = self.env.path2doc(name.strip() + '.rst')
link = posixpath.join('generated', standard_prefix, schema)
links.append((schema, link))
tocnode = addnodes.toctree()
tocnode['includefiles'] = [x[1] for x in links]
tocnode['entries'] = links
tocnode['maxdepth'] = -1
tocnode['glob'] = None
return [tocnode]
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.warnings = []
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:
suffixes = env.config.source_suffix
# adapt to a change with sphinx 1.3:
# for sphinx >= 1.3 env.config.source_suffix is a list
# see sphinx-doc/sphinx@bf3bdcc7f505a2761c0e83c9b1550e7206929f74
if map(int, sphinx.__version__.split(".")[:2]) < [1, 3]:
suffixes = [suffixes]
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)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
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, docname_) for docname_ in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
nodes.append(tocnode)
return self.warnings + nodes
def render_toc(self):
"""Render toctree"""
# get generated stub files
# example: ( "path/to/stubfile.rst", "path/to/", "stubfile", ".rst")
docs = self._app.generated_automodules_docs
# get modules which needs to be documented
content = self._content
excluded = self._options.get('exclude-members', '')
analyzer = self._app._sphinxjs_analyzer
modules = []
for module_spec in content:
modules += [
module.name for module in analyzer.resolve_name(module_spec)
]
# filter generated stub files
docs = [
doc for doc in docs if doc[2] in modules and doc[2] not in excluded
]
dirname = posixpath.dirname(self._env.docname)
tree_prefix = self._options['toctree'].strip()
docnames = []
# excluded = Matcher(self.config.exclude_patterns)
for path, dirpath, name, suffix in docs:
docname = posixpath.join(tree_prefix, name)
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in self._env.found_docs:
msg = __('automodule: stub file not found %s.' % name)
logger.warning(prefix, msg)
continue
docnames.append(docname)
if docnames:
# generate toctree
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docn) for docn in sorted(docnames)]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
return [automodulestoctree('', '', tocnode)]
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.warnings = []
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:
suffixes = env.config.source_suffix
# adapt to a change with sphinx 1.3:
# for sphinx >= 1.3 env.config.source_suffix is a list
# see sphinx-doc/sphinx@bf3bdcc7f505a2761c0e83c9b1550e7206929f74
if map(int, sphinx.__version__.split(".")[:2]) < [1, 3]:
suffixes = [suffixes]
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)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
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, docname_) for docname_ in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
nodes.append(tocnode)
return self.warnings + nodes
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.warnings = []
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)
if 'hidden' in self.options:
nodes = []
else:
nodes = self.get_table(items)
if 'toctree' in self.options:
suffix = env.config.source_suffix
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)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
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, docname) for docname in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
if not 'hidden' in self.options:
nodes.append(tocnode)
return self.warnings + nodes
def run(self):
env = self.state.document.settings.env
output = []
entries = []
includefiles = []
for entry in self.content:
if not entry:
continue
docname = docname_join(env.docname, entry)
if docname not in env.found_docs:
output.append(
self.state.document.reporter.warning(
"feed contains a reference to nonexisting " "document %r" % docname, line=self.lineno
)
)
env.note_reread()
else:
output.append(self.state.document.reporter.warning("file exists %r" % docname, line=self.lineno))
entries.append((None, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode["parent"] = env.docname
subnode["entries"] = entries
subnode["includefiles"] = includefiles
subnode["maxdepth"] = 1
subnode["glob"] = False
subnode["hidden"] = True
subnode["numbered"] = False
subnode["titlesonly"] = False
wrappernode = nodes.compound(classes=["toctree-wrapper"])
wrappernode.append(subnode)
output.append(wrappernode)
subnode = feed()
subnode["entries"] = includefiles
subnode["rss"] = self.options.get("rss")
subnode["title"] = self.options.get("title", "")
subnode["link"] = self.options.get("link", "")
subnode["description"] = self.options.get("description", "")
output.append(subnode)
return output
def run(self):
names = []
names += [x.strip() for x in self.content if x.strip()]
table, warnings, real_names = get_autosummary(
names, self.state, 'nosignatures' in self.options)
node = table
env = self.state.document.settings.env
suffix = env.config.source_suffix
all_docnames = env.found_docs.copy()
dirname = posixpath.dirname(env.docname)
if 'toctree' in self.options:
tree_prefix = self.options['toctree'].strip()
docnames = []
for name in names:
name = real_names.get(name, name)
docname = posixpath.join(tree_prefix, name)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
warnings.append(
self.state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=self.lineno))
docnames.append(docname)
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docname) for docname in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
return warnings + [node] + [tocnode]
else:
return warnings + [node]
def run(self):
names = []
names += [x.strip() for x in self.content if x.strip()]
table, warnings, real_names = get_autosummary(
names, self.state, 'nosignatures' in self.options)
node = table
env = self.state.document.settings.env
suffix = env.config.source_suffix
all_docnames = env.found_docs.copy()
dirname = posixpath.dirname(env.docname)
if 'toctree' in self.options:
tree_prefix = self.options['toctree'].strip()
docnames = []
for name in names:
name = real_names.get(name, name)
docname = posixpath.join(tree_prefix, name)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
warnings.append(self.state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=self.lineno))
docnames.append(docname)
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docname) for docname in docnames]
tocnode['maxdepth'] = -1
tocnode['glob'] = None
tocnode = autosummary_toc('', '', tocnode)
return warnings + [node] + [tocnode]
else:
return warnings + [node]
def run(self):
env = self.state.document.settings.env
ret = []
entries = []
includefiles = []
for entry in self.content:
if not entry:
continue
docname = docname_join(env.docname, entry)
if docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname,
line=self.lineno))
env.note_reread()
else:
entries.append((None, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
subnode['entries'] = entries
subnode['includefiles'] = includefiles
subnode['maxdepth'] = 1
subnode['glob'] = False
subnode['hidden'] = True
subnode['numbered'] = False
subnode['titlesonly'] = False
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
subnode = blogtree()
subnode['entries'] = includefiles
subnode['output'] = self.options.get('output')
subnode['title'] = self.options.get('title', '')
subnode['link'] = self.options.get('link', '')
subnode['description'] = self.options.get('description', '')
ret.append(subnode)
return ret
def run(self):
env = self.state.document.settings.env
output = []
entries = []
includefiles = []
for entry in self.content:
if not entry:
continue
docname = docname_join(env.docname, entry)
if docname not in env.found_docs:
output.append(self.state.document.reporter.warning(
'feed contains a reference to nonexisting '
'document %r' % docname, line=self.lineno))
env.note_reread()
else:
entries.append((None, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
subnode['entries'] = entries
subnode['includefiles'] = includefiles
subnode['maxdepth'] = 1
subnode['glob'] = False
subnode['hidden'] = True
subnode['numbered'] = False
subnode['titlesonly'] = False
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
output.append(wrappernode)
subnode = feed()
subnode['entries'] = includefiles
subnode['rss'] = self.options.get('rss')
subnode['title'] = self.options.get('title', '')
subnode['link'] = self.options.get('link', '')
subnode['description'] = self.options.get('description', '')
output.append(subnode)
return output
def autosummary_directive(dirname, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
names = []
names += [x for x in content if x.strip()]
result, warnings = get_autosummary(names, state.document)
node = nodes.paragraph()
state.nested_parse(result, 0, node)
env = state.document.settings.env
suffix = env.config.source_suffix
all_docnames = env.found_docs.copy()
dirname = posixpath.dirname(env.docname)
docnames = []
doctitles = {}
for docname in names:
docname = 'generated/' + docname
doctitles[docname] = ''
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
warnings.append(
state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=lineno))
docnames.append(docname)
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['includetitles'] = doctitles
tocnode['maxdepth'] = -1
tocnode['glob'] = None
return warnings + node.children + [tocnode]
def run(self):
# type: () -> List[nodes.Node]
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno)
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(self.env.docname)
tree_prefix = self.options['toctree'].strip()
docnames = []
excluded = Matcher(self.config.exclude_patterns)
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 self.env.found_docs:
if excluded(self.env.doc2path(docname, None)):
self.warn('toctree references excluded document %r'
% docname)
else:
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
nodes.append(autosummary_toc('', '', tocnode))
return nodes
def run(self):
# type: () -> List[nodes.Node]
subnode = addnodes.toctree()
subnode['parent'] = self.env.docname
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
subnode['entries'] = []
subnode['includefiles'] = []
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = 'glob' in self.options
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret = self.parse_content(subnode)
ret.append(wrappernode)
return ret
def autosummary_directive(dirname, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
names = []
names += [x for x in content if x.strip()]
result, warnings = get_autosummary(names, state.document)
node = nodes.paragraph()
state.nested_parse(result, 0, node)
env = state.document.settings.env
suffix = env.config.source_suffix
all_docnames = env.found_docs.copy()
dirname = posixpath.dirname(env.docname)
docnames = []
doctitles = {}
for docname in names:
docname = 'generated/' + docname
doctitles[docname] = ''
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
docname = posixpath.normpath(posixpath.join(dirname, docname))
if docname not in env.found_docs:
warnings.append(state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=lineno))
docnames.append(docname)
tocnode = addnodes.toctree()
tocnode['includefiles'] = docnames
tocnode['includetitles'] = doctitles
tocnode['maxdepth'] = -1
tocnode['glob'] = None
return warnings + node.children + [tocnode]
def my_toctree_run(self):
"""Show non existing entries of toctree
Used to replace the function -> sphinx.directives.other.TocTree.run
Only %r following are replaced %s to avoid unreadable string.
"""
env = self.state.document.settings.env
suffix = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if not glob:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(self.state.document.reporter.warning(
u'toctree contains reference to nonexisting '
u'document %s' % docname, line=self.lineno))
env.note_reread()
else:
entries.append((title, docname))
includefiles.append(docname)
else:
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %s didn\'t match any documents'
% entry, line=self.lineno))
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['numbered'] = 'numbered' in self.options
subnode['titlesonly'] = 'titlesonly' in self.options
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
return ret
def run(self):
# type: () -> List[nodes.Node]
env = self.state.document.settings.env
suffixes = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# Children of the internal toctree node; these will be rewritten by
# traversals (and so having other references into these will also
# get rewritten) but, nicely, are not rendered directly due to the
# way that the environment code deals with toctrees.
others = []
# (title, ref) pairs, where ref may be a document, or an external link,
# or a node. title may be None if the document's title is to be used
# and must be None if a node is given as a ref.
entries = [] # type: List[Tuple[unicode, Union[unicode,nodes.Node]]]
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if entry.startswith("_ "):
node = nodes.paragraph()
self.state.nested_parse(ViewList([entry[2:]]), 0, node)
others.append(node)
entries.append((None, node))
elif glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname,
line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
entries.reverse()
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
subnode.children = others
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
def build_details_table(self, resource):
env = self.state.document.settings.env
app = env.app
is_list = 'is-list' in self.options
table = nodes.table(classes=['resource-info'])
tgroup = nodes.tgroup(cols=2)
table += tgroup
tgroup += nodes.colspec(colwidth=30, classes=['field'])
tgroup += nodes.colspec(colwidth=70, classes=['value'])
tbody = nodes.tbody()
tgroup += tbody
# Name
if is_list:
resource_name = resource.name_plural
else:
resource_name = resource.name
append_detail_row(tbody, "Name", nodes.literal(text=resource_name))
# URI
uri_template = get_resource_uri_template(resource, not is_list)
append_detail_row(tbody, "URI", nodes.literal(text=uri_template))
# Required features
if getattr(resource, 'required_features', False):
feature_list = nodes.bullet_list()
for feature in resource.required_features:
item = nodes.list_item()
paragraph = nodes.paragraph()
paragraph += nodes.inline(text=feature.feature_id)
item += paragraph
feature_list += item
append_detail_row(tbody, 'Required Features', feature_list)
# Token Policy ID
if hasattr(resource, 'policy_id'):
append_detail_row(tbody, "Token Policy ID",
nodes.literal(text=resource.policy_id))
# HTTP Methods
allowed_http_methods = self.get_http_methods(resource, is_list)
bullet_list = nodes.bullet_list()
for http_method in allowed_http_methods:
item = nodes.list_item()
bullet_list += item
paragraph = nodes.paragraph()
item += paragraph
ref = nodes.reference(text=http_method, refid=http_method)
paragraph += ref
doc_summary = self.get_doc_for_http_method(resource, http_method)
i = doc_summary.find('.')
if i != -1:
doc_summary = doc_summary[:i + 1]
paragraph += nodes.inline(text=" - ")
paragraph += parse_text(
self, doc_summary,
wrapper_node_type=nodes.inline,
where='HTTP %s handler summary for %s'
% (http_method, self.options['classname']))
append_detail_row(tbody, "HTTP Methods", bullet_list)
# Parent Resource
if is_list or resource.uri_object_key is None:
parent_resource = resource._parent_resource
is_parent_list = False
else:
parent_resource = resource
is_parent_list = True
if parent_resource:
paragraph = nodes.paragraph()
paragraph += get_ref_to_resource(app, parent_resource,
is_parent_list)
else:
paragraph = 'None.'
append_detail_row(tbody, "Parent Resource", paragraph)
# Child Resources
if is_list:
child_resources = list(resource.list_child_resources)
if resource.name != resource.name_plural:
if resource.uri_object_key:
child_resources.append(resource)
are_children_lists = False
else:
are_children_lists = True
else:
child_resources = resource.item_child_resources
are_children_lists = True
if child_resources:
tocnode = addnodes.toctree()
tocnode['glob'] = None
tocnode['maxdepth'] = 1
tocnode['hidden'] = False
docnames = sorted([
docname_join(env.docname,
get_resource_docname(app, child_resource,
are_children_lists))
for child_resource in child_resources
])
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docname) for docname in docnames]
else:
tocnode = nodes.paragraph(text="None")
append_detail_row(tbody, "Child Resources", tocnode)
# Anonymous Access
if is_list and not resource.singleton:
getter = resource.get_list
else:
getter = resource.get
if getattr(getter, 'login_required', False):
anonymous_access = 'No'
elif getattr(getter, 'checks_login_required', False):
anonymous_access = 'Yes, if anonymous site access is enabled'
else:
anonymous_access = 'Yes'
append_detail_row(tbody, "Anonymous Access", anonymous_access)
return table
def build_details_table(self, resource):
is_list = "is-list" in self.options
table = nodes.table(classes=["resource-info"])
tgroup = nodes.tgroup(cols=2)
table += tgroup
tgroup += nodes.colspec(colwidth=30, classes=["field"])
tgroup += nodes.colspec(colwidth=70, classes=["value"])
tbody = nodes.tbody()
tgroup += tbody
# Name
if is_list:
resource_name = resource.name_plural
else:
resource_name = resource.name
append_detail_row(tbody, "Name", nodes.literal(text=resource_name))
# URI
uri_template = get_resource_uri_template(resource, not is_list)
append_detail_row(tbody, "URI", nodes.literal(text=uri_template))
# Token Policy ID
if hasattr(resource, "policy_id"):
append_detail_row(tbody, "Token Policy ID", nodes.literal(text=resource.policy_id))
# HTTP Methods
allowed_http_methods = self.get_http_methods(resource, is_list)
bullet_list = nodes.bullet_list()
for http_method in allowed_http_methods:
item = nodes.list_item()
bullet_list += item
paragraph = nodes.paragraph()
item += paragraph
ref = nodes.reference(text=http_method, refid=http_method)
paragraph += ref
doc_summary = self.get_doc_for_http_method(resource, http_method)
i = doc_summary.find(".")
if i != -1:
doc_summary = doc_summary[: i + 1]
paragraph += nodes.inline(text=" - ")
paragraph += parse_text(
self,
doc_summary,
nodes.inline,
where="HTTP %s handler summary for %s" % (http_method, self.options["classname"]),
)
append_detail_row(tbody, "HTTP Methods", bullet_list)
# Parent Resource
if is_list or resource.uri_object_key is None:
parent_resource = resource._parent_resource
is_parent_list = False
else:
parent_resource = resource
is_parent_list = True
if parent_resource:
paragraph = nodes.paragraph()
paragraph += get_ref_to_resource(parent_resource, is_parent_list)
else:
paragraph = "None."
append_detail_row(tbody, "Parent Resource", paragraph)
# Child Resources
if is_list:
child_resources = list(resource.list_child_resources)
if resource.name != resource.name_plural:
if resource.uri_object_key:
child_resources.append(resource)
are_children_lists = False
else:
are_children_lists = True
else:
child_resources = resource.item_child_resources
are_children_lists = True
if child_resources:
tocnode = addnodes.toctree()
tocnode["glob"] = None
tocnode["maxdepth"] = 1
tocnode["hidden"] = False
docnames = sorted(
[
docname_join(
self.state.document.settings.env.docname,
get_resource_docname(child_resource, are_children_lists),
)
for child_resource in child_resources
]
)
tocnode["includefiles"] = docnames
tocnode["entries"] = [(None, docname) for docname in docnames]
else:
tocnode = nodes.paragraph(text="None")
append_detail_row(tbody, "Child Resources", tocnode)
# Anonymous Access
if is_list and not resource.singleton:
getter = resource.get_list
else:
getter = resource.get
if getattr(getter, "login_required", False):
anonymous_access = "No"
elif getattr(getter, "checks_login_required", False):
anonymous_access = "Yes, if anonymous site access is enabled"
else:
anonymous_access = "Yes"
append_detail_row(tbody, "Anonymous Access", anonymous_access)
return table
def run(self):
env = self.state.document.settings.env
if not hasattr(env, 'guide_all_guides'):
return []
guides = {}
for guide in env.guide_all_guides:
guides[guide['docname']] = guide
cardset = CardSet()
previous_line = None
pending_card = [None]
def handle_single_guide():
if pending_card[0] is None:
if previous_line not in guides:
return
guide = guides[previous_line]
cardset.add_guide(env, guide)
else:
cardset_guides = [
guides[docname] for docname in pending_card[0]['guides']
if docname in guides
]
cardset.add_guides(env, cardset_guides,
pending_card[0]['title'])
pending_card[0] = None
for is_indented, lineno, line in parse_indentation(self.content):
if not line:
continue
if is_indented:
# A card containing multiple guides
if pending_card[0] is None:
pending_card[0] = {
'title': previous_line,
'jumbo': False,
'guides': []
}
pending_card[0]['guides'].append(line)
elif previous_line is not None:
# A card containing a single guide
handle_single_guide()
previous_line = line
if previous_line is not None:
handle_single_guide()
try:
rendered = GUIDES_INDEX_TEMPLATE.render({
'categories': [
cat for cat in cardset.categories.values()
if cat['n_guides'] > 0
],
'link_suffix':
env.app.builder.link_suffix
})
except Exception as error:
raise self.severe('Failed to render template: {}'.format(
ErrorString(error)))
rendered_lines = statemachine.string2lines(rendered,
4,
convert_whitespace=1)
self.state_machine.insert_input(rendered_lines, '')
# Add guides to the TOC
subnode = addnodes.toctree()
subnode['hidden'] = True
subnode['glob'] = False
subnode['includefiles'] = list(guides.keys())
subnode['parent'] = env.docname
subnode['entries'] = [(guide['title'], guide['docname'])
for guide in guides.values()]
set_source_info(self, subnode)
return [subnode]
def run(self):
env = self.state.document.settings.env
suffixes = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
try:
all_docnames.remove(env.docname)
except KeyError:
if env.docname == "<<string>>":
# This comes from rst2html.
pass
else:
logger = logging.getLogger("CustomTocTreeCollector")
logger.warning(
"[CustomTocTreeCollector] unable to remove document '{0}' from {1}"
.format(env.docname, ", ".join(all_docnames)))
for entry in self.content:
if not entry:
continue
if glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'[CustomTocTree] glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
'[CustomTocTree] contains reference to nonexisting '
'document %r' % docname,
line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
entries.reverse()
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
def my_toctree_run(self):
"""Show non existing entries of toctree
:param sphinx.directives.other.TocTree self: The instance object
:rtype: list
:return: list of the nodes made in this method
Defined to replace the method :meth:`sphinx.directives.other.TocTree.run`
Only :code:`%r` following are replaced with :code:`%s` to avoid unreadable string.
"""
env = self.state.document.settings.env
suffixes = env.config.source_suffix
glob = 'glob' in self.options
caption = self.options.get('caption')
if caption:
self.options.setdefault('name', nodes.fully_normalize_name(caption))
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents' %
entry,
line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
u'toctree contains reference to nonexisting '
u'document %s' % docname,
line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = caption
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
def run(self):
env = self.state.document.settings.env
suffix = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
includetitles = {}
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if not glob:
# look for explicit titles ("Some Title <document>")
m = caption_ref_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
# elif docname not in env.found_docs:
# ret.append(self.state.document.reporter.warning(
# 'toctree references unknown document %r' % docname,
# line=self.lineno))
else:
entries.append((title, docname))
includefiles.append(docname)
else:
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['numbered'] = 'numbered' in self.options
ret.append(subnode)
return ret
def run(self):
env = self.state.document.settings.env
suffixes = env.config.source_suffix
glob = 'glob' in self.options
caption = self.options.get('caption')
if caption:
self.options.setdefault('name', nodes.fully_normalize_name(caption))
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname, line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = caption
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
class Latest(Directive):
"""
Directive to notify Sphinx about the hierarchical structure of the docs,
and to include a table-of-contents like tree in the current document.
"""
has_content = True
required_arguments = 0
optional_arguments = 0
final_argument_whitespace = False
option_spec = {
'maxdepth': int,
'limit': int,
'glob': directives.flag,
'hidden': directives.flag,
'numbered': int_or_nothing,
'titlesonly': directives.flag,
}
def run(self):
env = self.state.document.settings.env
suffix = env.config.source_suffix
glob = 'glob' in self.options
limit = 'limit' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if not glob:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname,
line=self.lineno))
env.note_reread()
else:
entries.append((title, docname))
includefiles.append(docname)
else:
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
sorted_entries = {}
for entry in entries:
metadata = env.metadata.get(entry[1], {})
if 'date' not in metadata:
continue
try:
pub_date = parse_date(metadata['date'])
env.metadata.get(entry[1], {})
except ValueError, exc:
continue
sorted_entries[pub_date.isoformat()] = entry
ordered_keys = sorted_entries.keys()
ordered_keys.sort(reverse=True)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = []
for date in ordered_keys:
subnode['entries'].append(sorted_entries[date])
if limit:
del subnode['entries'][self.options.get('limit'
):len(subnode['entries'])]
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
return ret
def run(self):
# type: () -> List[nodes.Node]
suffixes = self.config.source_suffix
glob = 'glob' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = [] # type: List[Tuple[unicode, unicode]]
includefiles = []
all_docnames = self.env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(self.env.docname)
for entry in self.content:
if not entry:
continue
# look for explicit titles ("Some Title <document>")
explicit = explicit_title_re.match(entry)
if glob and ('*' in entry or '?' in entry
or '[' in entry) and not explicit:
patname = docname_join(self.env.docname, entry)
docnames = sorted(patfilter(all_docnames,
patname)) # type: ignore
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
else:
if explicit:
ref = explicit.group(2)
title = explicit.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(self.env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in self.env.found_docs:
ret.append(
self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname,
line=self.lineno))
self.env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = self.env.docname
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
entries.reverse()
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
def run(self):
env = self.state.document.settings.env
suffix = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# (title, ref) pairs, where ref may be a document, or an external link,
# and title may be None if the document's title is to be used
entries = []
includefiles = []
includetitles = {}
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if not glob:
# look for explicit titles ("Some Title <document>")
m = caption_ref_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(
self.state.document.reporter.warning(
'toctree references unknown document %r' % docname,
line=self.lineno))
else:
entries.append((title, docname))
includefiles.append(docname)
else:
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['numbered'] = 'numbered' in self.options
ret.append(subnode)
return ret
def build_details_table(self, resource):
is_list = 'is-list' in self.options
table = nodes.table()
tgroup = nodes.tgroup(cols=2)
table += tgroup
tgroup += nodes.colspec(colwidth=30)
tgroup += nodes.colspec(colwidth=70)
tbody = nodes.tbody()
tgroup += tbody
# Name
if is_list:
resource_name = resource.name_plural
else:
resource_name = resource.name
append_detail_row(tbody, "Name", nodes.literal(text=resource_name))
# URI
uri_template = get_resource_uri_template(resource, not is_list)
append_detail_row(tbody, "URI", nodes.literal(text=uri_template))
# URI Parameters
#append_detail_row(tbody, "URI Parameters", '')
# Description
append_detail_row(tbody, "Description",
parse_text(self, inspect.getdoc(resource)))
# HTTP Methods
allowed_http_methods = self.get_http_methods(resource, is_list)
bullet_list = nodes.bullet_list()
for http_method in allowed_http_methods:
item = nodes.list_item()
bullet_list += item
paragraph = nodes.paragraph()
item += paragraph
ref = nodes.reference(text=http_method, refid=http_method)
paragraph += ref
doc_summary = self.get_doc_for_http_method(resource, http_method)
i = doc_summary.find('.')
if i != -1:
doc_summary = doc_summary[:i + 1]
paragraph += nodes.inline(text=" - ")
paragraph += parse_text(self, doc_summary, nodes.inline)
append_detail_row(tbody, "HTTP Methods", bullet_list)
# Parent Resource
if is_list or resource.uri_object_key is None:
parent_resource = resource._parent_resource
is_parent_list = False
else:
parent_resource = resource
is_parent_list = True
if parent_resource:
paragraph = nodes.paragraph()
paragraph += get_ref_to_resource(parent_resource, is_parent_list)
else:
paragraph = 'None.'
append_detail_row(tbody, "Parent Resource", paragraph)
# Child Resources
if is_list:
child_resources = list(resource.list_child_resources)
if resource.name != resource.name_plural:
if resource.uri_object_key:
child_resources.append(resource)
are_children_lists = False
else:
are_children_lists = True
else:
child_resources = resource.item_child_resources
are_children_lists = True
if child_resources:
tocnode = addnodes.toctree()
tocnode['glob'] = None
tocnode['maxdepth'] = 1
tocnode['hidden'] = False
docnames = sorted([
docname_join(self.state.document.settings.env.docname,
get_resource_docname(child_resource,
are_children_lists))
for child_resource in child_resources
])
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docname) for docname in docnames]
else:
tocnode = nodes.paragraph(text="None")
append_detail_row(tbody, "Child Resources", tocnode)
# Anonymous Access
if is_list and not resource.singleton:
getter = resource.get_list
else:
getter = resource.get
if getattr(getter, 'login_required', False):
anonymous_access = 'No'
elif getattr(getter, 'checks_login_required', False):
anonymous_access = 'Yes, if anonymous site access is enabled'
else:
anonymous_access = 'Yes'
append_detail_row(tbody, "Anonymous Access", anonymous_access)
return table
def build_details_table(self, resource):
is_list = 'is-list' in self.options
table = nodes.table()
tgroup = nodes.tgroup(cols=1)
table += tgroup
tgroup += nodes.colspec(colwidth=30)
tgroup += nodes.colspec(colwidth=70)
tbody = nodes.tbody()
tgroup += tbody
# Name
if is_list:
resource_name = resource.name_plural
else:
resource_name = resource.name
self.append_detail_row(tbody, "Name", nodes.literal(text=resource_name))
# URI
request = DummyRequest()
uri_template = get_resource_uri_template(resource, not is_list)
self.append_detail_row(tbody, "URI", nodes.literal(text=uri_template))
# URI Parameters
#self.append_detail_row(tbody, "URI Parameters", '')
# Description
self.append_detail_row(tbody, "Description",
parse_text(self, inspect.getdoc(resource)))
# HTTP Methods
allowed_http_methods = self.get_http_methods(resource, is_list)
bullet_list = nodes.bullet_list()
for http_method in allowed_http_methods:
item = nodes.list_item()
bullet_list += item
paragraph = nodes.paragraph()
item += paragraph
ref = nodes.reference(text=http_method, refid=http_method)
paragraph += ref
doc_summary = self.get_doc_for_http_method(resource, http_method)
i = doc_summary.find('.')
if i != -1:
doc_summary = doc_summary[:i + 1]
paragraph += nodes.inline(text=" - ")
paragraph += parse_text(self, doc_summary, nodes.inline)
self.append_detail_row(tbody, "HTTP Methods", bullet_list)
# Parent Resource
if is_list or resource.uri_object_key is None:
parent_resource = resource._parent_resource
is_parent_list = False
else:
parent_resource = resource
is_parent_list = True
if parent_resource:
paragraph = nodes.paragraph()
paragraph += get_ref_to_resource(parent_resource, is_parent_list)
else:
paragraph = 'None.'
self.append_detail_row(tbody, "Parent Resource", paragraph)
# Child Resources
if is_list:
child_resources = list(resource.list_child_resources)
if resource.name != resource.name_plural:
if resource.uri_object_key:
child_resources.append(resource)
are_children_lists = False
else:
are_children_lists = True
else:
child_resources = resource.item_child_resources
are_children_lists = True
if child_resources:
tocnode = addnodes.toctree()
tocnode['glob'] = None
tocnode['maxdepth'] = 1
tocnode['hidden'] = False
docnames = sorted([
docname_join(self.state.document.settings.env.docname,
get_resource_docname(child_resource,
are_children_lists))
for child_resource in child_resources
])
tocnode['includefiles'] = docnames
tocnode['entries'] = [(None, docname) for docname in docnames]
else:
tocnode = nodes.paragraph(text="None")
self.append_detail_row(tbody, "Child Resources", tocnode)
# Anonymous Access
if is_list:
getter = resource.get_list
else:
getter = resource.get
if getattr(getter, 'login_required', False):
anonymous_access = 'No'
elif getattr(getter, 'checks_login_required', False):
anonymous_access = 'Yes, if anonymous site access is enabled'
else:
anonymous_access = 'Yes'
self.append_detail_row(tbody, "Anonymous Access", anonymous_access)
return table
def run(self):
# type: () -> List[nodes.Node]
env = self.state.document.settings.env
suffixes = env.config.source_suffix
glob = 'glob' in self.options
ret = []
# Children of the internal toctree node; these will be rewritten by
# traversals (and so having other references into these will also
# get rewritten) but, nicely, are not rendered directly due to the
# way that the environment code deals with toctrees.
others = []
# (title, ref) pairs, where ref may be a document, or an external link,
# or a node. title may be None if the document's title is to be used
# and must be None if a node is given as a ref.
entries = [] # type: List[Tuple[unicode, Union[unicode,nodes.Node]]]
includefiles = []
all_docnames = env.found_docs.copy()
# don't add the currently visited file in catch-all patterns
all_docnames.remove(env.docname)
for entry in self.content:
if not entry:
continue
if entry.startswith("_ "):
node = nodes.paragraph()
self.state.nested_parse(ViewList([entry[2:]]), 0, node)
others.append(node)
entries.append((None, node))
elif glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
ref = m.group(2)
title = m.group(1)
docname = ref
else:
ref = docname = entry
title = None
# remove suffixes (backwards compatibility)
for suffix in suffixes:
if docname.endswith(suffix):
docname = docname[:-len(suffix)]
break
# absolutize filenames
docname = docname_join(env.docname, docname)
if url_re.match(ref) or ref == 'self':
entries.append((title, ref))
elif docname not in env.found_docs:
ret.append(self.state.document.reporter.warning(
'toctree contains reference to nonexisting '
'document %r' % docname, line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
entries.reverse()
subnode['entries'] = entries
# includefiles only entries that are documents
subnode['includefiles'] = includefiles
subnode['maxdepth'] = self.options.get('maxdepth', -1)
subnode['caption'] = self.options.get('caption')
subnode['glob'] = glob
subnode['hidden'] = 'hidden' in self.options
subnode['includehidden'] = 'includehidden' in self.options
subnode['numbered'] = self.options.get('numbered', 0)
subnode['titlesonly'] = 'titlesonly' in self.options
subnode.children = others
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
self.add_name(wrappernode)
ret.append(wrappernode)
return ret
