def parse_content(self, toctree):
env = self.state.document.settings.env
suffixes = env.config.source_suffix
# glob target documents
all_docnames = env.found_docs.copy()
all_docnames.remove(env.docname) # remove current document
ret = []
for entry in self.content:
if not entry:
continue
# look for explicit titles ("Some Title <document>")
explicit = explicit_title_re.match(entry)
if (toctree['glob'] and glob_re.match(entry) and
not explicit and not url_re.match(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
toctree['entries'].append((None, docname))
toctree['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(env.docname, docname)
if url_re.match(ref) or ref == 'self':
toctree['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)
toctree['entries'].append((title, docname))
toctree['includefiles'].append(docname)
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
toctree['entries'] = list(reversed(toctree['entries']))
return ret
def parse_content(self, toctree):
suffixes = self.config.source_suffix
# glob target documents
all_docnames = self.env.found_docs.copy()
all_docnames.remove(self.env.docname) # remove current document
ret = []
for entry in self.content:
if not entry:
continue
# look for explicit titles ("Some Title <document>")
explicit = explicit_title_re.match(entry)
if (toctree['glob'] and glob_re.match(entry) and
not explicit and not url_re.match(entry)):
patname = docname_join(self.env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
toctree['entries'].append((None, docname))
toctree['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':
toctree['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)
toctree['entries'].append((title, docname))
toctree['includefiles'].append(docname)
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
toctree['entries'] = list(reversed(toctree['entries']))
return ret
def _resolve_doc_xref(
self,
env: BuildEnvironment,
fromdocname: str,
builder: Builder,
typ: str,
target: str,
node: pending_xref,
contnode: Element,
) -> Element:
"""XXX copied from sphinx/sphinx/domains/std.py XXX"""
# directly reference to document by source name
# can be absolute or relative
refdoc = node.get("refdoc", fromdocname)
docname = docname_join(refdoc, node["reftarget"])
if docname not in env.all_docs:
return None
else:
if node["refexplicit"]:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(env.titles[docname])
innernode = inline(caption, caption, classes=["doc"])
return make_refnode(builder, fromdocname, docname, None, innernode)
def get_doctitle_for(self, node):
refdoc = node.get('refdoc', 'index')
docname = docname_join(refdoc, node['reftarget'])
if docname not in self.env.all_docs:
return None
else:
return clean_astext(self.env.titles[docname])
def get_rst(self):
env = self.state.document.settings.env
entries = []
all_docnames = env.found_docs.copy()
found = set([env.docname]) # don't include myself
for entry in self.content:
if not entry:
continue
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
if not docname in found:
found.add(docname)
entries.append(self.entry_class.create(env, docname))
expr = self.options.get('filter')
if expr:
def func(e):
return eval(expr, dict(e=e))
entries = list(filter(func, entries))
orderby = self.options.get('orderby')
if orderby:
def func(a, b):
va = getattr(a, orderby, '')
vb = getattr(b, orderby, '')
return cmp(va, vb)
entries = sorted(entries, func)
headers = self.get_headers()
rows = []
for e in entries:
rows.append(self.format_entry(e))
return rstgen.table(headers, rows)
def _resolve_doc_nested(self, node: pending_xref,
fromdocname: str) -> Optional[Element]:
"""This is the same as ``sphinx.domains.std._resolve_doc_xref``,
but allows for nested syntax, rather than converting the inner node to raw text.
It also allows for extensions on document names.
"""
# directly reference to document by source name; can be absolute or relative
refdoc = node.get("refdoc", fromdocname)
docname = docname_join(refdoc, node["reftarget"])
if docname not in self.env.all_docs:
# try stripping known extensions from doc name
if os.path.splitext(docname)[1] in self.env.config.source_suffix:
docname = os.path.splitext(docname)[0]
if docname not in self.env.all_docs:
return None
if node["refexplicit"]:
# reference with explicit title
caption = node.astext()
innernode = nodes.inline(caption, "", classes=["doc"])
innernode.extend(node[0].children)
else:
# TODO do we want nested syntax for titles?
caption = clean_astext(self.env.titles[docname])
innernode = nodes.inline(caption, caption, classes=["doc"])
return make_refnode(self.app.builder, fromdocname, docname, "",
innernode)
def get_rst(self):
env = self.state.document.settings.env
entries = []
all_docnames = env.found_docs.copy()
found = set([env.docname]) # don't include myself
for entry in self.content:
if not entry:
continue
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
if not docname in found:
found.add(docname)
entries.append(self.entry_class.create(env, docname))
expr = self.options.get('filter')
if expr:
def func(e):
try:
return eval(expr, dict(e=e))
except Exception as exc:
return "{} in {}".format(exc, expr)
entries = list(filter(func, entries))
orderby = self.options.get('orderby')
if orderby:
def func(a):
return getattr(a, orderby, '')
entries = sorted(entries, key=func)
headers = self.get_headers()
rows = []
for e in entries:
rows.append(self.format_entry(e))
return rstgen.table(headers, rows)
def get_title_for(self, node):
refdoc = node.get('refdoc', 'index')
docname = docname_join(refdoc, node['reftarget'])
if docname not in self.env.all_docs:
return None
else:
title = clean_astext(self.env.titles[docname])
sectnum = self.config.section_numbers.get(docname)
if sectnum:
return u"%s「%s」" % (sectnum, title)
else:
return title
def _missing_reference(app, env, node, contnode):
from docutils import nodes
from docutils.utils import relative_path
from sphinx.util import docname_join
doctarget = docname_join(node["refdoc"], node["reftarget"])
if doctarget.startswith(origin):
routed_doctarget = doctarget.replace(origin, destination)
if routed_doctarget in env.all_docs:
newnode = nodes.reference("", contnode.astext(), internal=True)
newnode["refuri"] = app.builder.get_relative_uri(
node["refdoc"], routed_doctarget)
return newnode
def _resolve_doc_xref(self, env, fromdocname, builder, typ, target, node, contnode):
# type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA
# directly reference to document by source name; can be absolute or relative
refdoc = node.get('refdoc', fromdocname)
docname = docname_join(refdoc, node['reftarget'])
if docname not in env.all_docs:
return None
else:
if node['refexplicit']:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(env.titles[docname])
innernode = nodes.inline(caption, caption, classes=['doc'])
return make_refnode(builder, fromdocname, docname, None, innernode)
def _resolve_doc_xref(self, env, fromdocname, builder, typ, target, node, contnode):
# type: (BuildEnvironment, str, Builder, str, str, addnodes.pending_xref, nodes.Element) -> nodes.Element # NOQA
# directly reference to document by source name; can be absolute or relative
refdoc = node.get('refdoc', fromdocname)
docname = docname_join(refdoc, node['reftarget'])
if docname not in env.all_docs:
return None
else:
if node['refexplicit']:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(env.titles[docname])
innernode = nodes.inline(caption, caption, classes=['doc'])
return make_refnode(builder, fromdocname, docname, None, innernode)
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 _resolve_doc_xref(self, env: "BuildEnvironment", fromdocname: str,
builder: "Builder", typ: str, target: str,
node: pending_xref, contnode: Element) -> Element:
# directly reference to document by source name; can be absolute or relative
refdoc = node.get('refdoc', fromdocname)
docname = docname_join(refdoc, node['reftarget'])
if docname not in env.all_docs:
return None
else:
if node['refexplicit']:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(env.titles[docname])
innernode = nodes.inline(caption, caption, classes=['doc'])
return make_refnode(builder, fromdocname, docname, None, innernode)
def _resolve_doc_reference(self, builder, refdoc, node, contnode):
# directly reference to document by source name;
# can be absolute or relative
docname = docname_join(refdoc, node['reftarget'])
if docname in self.all_docs:
if node['refexplicit']:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(self.titles[docname])
innernode = nodes.inline(caption, caption)
innernode['classes'].append('doc')
newnode = nodes.reference('', '', internal=True)
newnode['refuri'] = builder.get_relative_uri(refdoc, docname)
newnode.append(innernode)
return newnode
def _resolve_doc_reference(self, builder, refdoc, node, contnode):
# directly reference to document by source name;
# can be absolute or relative
docname = docname_join(refdoc, node['reftarget'])
if docname in self.all_docs:
if node['refexplicit']:
# reference with explicit title
caption = node.astext()
else:
caption = clean_astext(self.titles[docname])
innernode = nodes.inline(caption, caption)
innernode['classes'].append('doc')
newnode = nodes.reference('', '', internal=True)
newnode['refuri'] = builder.get_relative_uri(refdoc, docname)
newnode.append(innernode)
return newnode
def make_entry(self, title, ref, toctree, all_docnames, warnings):
"""Make a single toctree entry.
Args:
title: The optional title of the entry to be displayed. If None, the
title will be extracted from the referred document
ref: A reference to the linked document; a filename or URL
toctree: The toctree to which the entry will be added
all_docnames: A sequence of all docnames excluding the document containing
this directive.
warnings: A sequence of warnings to which additional warnings may be appended
"""
docname = ref
suffixes = self.config.source_suffix
excluded = Matcher(self.config.exclude_patterns)
# 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':
toctree['entries'].append((title, ref))
elif docname not in self.env.found_docs:
if excluded(self.env.doc2path(docname, None)):
message = 'toctree contains reference to excluded document %r'
else:
message = 'toctree contains reference to nonexisting document %r'
warnings.append(
self.state.document.reporter.warning(message % docname,
line=self.lineno))
self.env.note_reread()
else:
all_docnames.discard(docname)
toctree['entries'].append((title, docname))
toctree['includefiles'].append(docname)
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):
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 parse_iterable(self, references, toctree):
"""Build a TOC from a series of document links.
Args:
references: An iterable series of document links
toctree: The toctree node.
"""
# glob target documents
all_docnames = self.env.found_docs.copy()
all_docnames.remove(self.env.docname) # remove current document
warnings = []
for ref in references:
if not ref:
continue
if toctree['glob'] and glob_re.match(
ref) and not url_re.match(ref):
patname = docname_join(self.env.docname, ref)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
toctree['entries'].append((None, docname))
toctree['includefiles'].append(docname)
if not docnames:
warnings.append(
self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% ref,
line=self.lineno))
else:
self.make_entry(title=None,
ref=ref,
toctree=toctree,
all_docnames=all_docnames,
warnings=warnings)
return warnings
def run(self):
env = self.state.document.settings.env
output = []
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:
includefiles.append(docname)
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):
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 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
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
def parse_content(self, toctree: addnodes.toctree) -> List[Node]:
suffixes = self.config.source_suffix
# glob target documents
all_docnames = self.env.found_docs.copy()
all_docnames.remove(self.env.docname) # remove current document
ret: List[Node] = []
excluded = Matcher(self.config.exclude_patterns)
for entry in self.content:
if not entry:
continue
# look for explicit titles ("Some Title <document>")
explicit = explicit_title_re.match(entry)
if (toctree['glob'] and glob_re.match(entry) and not explicit
and not url_re.match(entry)):
patname = docname_join(self.env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
toctree['entries'].append((None, docname))
toctree['includefiles'].append(docname)
if not docnames:
logger.warning(__(
'toctree glob pattern %r didn\'t match any documents'),
entry,
location=toctree)
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':
toctree['entries'].append((title, ref))
elif docname not in self.env.found_docs:
if excluded(self.env.doc2path(docname, None)):
message = __(
'toctree contains reference to excluded document %r'
)
subtype = 'excluded'
else:
message = __(
'toctree contains reference to nonexisting document %r'
)
subtype = 'not_readable'
logger.warning(message,
docname,
type='toc',
subtype=subtype,
location=toctree)
self.env.note_reread()
else:
if docname in all_docnames:
all_docnames.remove(docname)
else:
logger.warning(
__('duplicated entry found in toctree: %s'),
docname,
location=toctree)
toctree['entries'].append((title, docname))
toctree['includefiles'].append(docname)
# entries contains all entries (self references, external links etc.)
if 'reversed' in self.options:
toctree['entries'] = list(reversed(toctree['entries']))
toctree['includefiles'] = list(reversed(toctree['includefiles']))
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
suffix = env.config.source_suffix
glob = 'glob' in self.options
# (title, ref) pairs, where ref may only be a document
# external links are forbidden, since we have no way of dating them
# 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)
ret = []
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 = 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(
'latest list glob pattern %r didn\'t match any documents'
% entry,
line=self.lineno))
subnode = latest()
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['titlesonly'] = 'titlesonly' in self.options
#what does this do?
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['feed-latest-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
return ret
def get_rst(self):
# return str(self.state.document.refnames)
env = self.state.document.settings.env
target = ' '.join(self.content).strip()
if not target:
target = env.temp_data['docname']
# print("20140409 target is %r" % target)
found = set()
rows = set()
# headers = 'children attributes \
# resolved referenced indirect_reference_name \
# tagname'.split()
for docname in env.found_docs:
if env.temp_data['docname'] == docname: # skip myself
continue
try:
doc = env.get_doctree(docname)
except Exception:
# 20140117 i had the following after a fab clean:
# File "/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/environment.py", line 1077, in get_doctree
# f = open(doctree_filename, 'rb')
# IOError: [Errno 2] No such file or directory: u'/home/luc/hgwork/lino/docs/.build/.doctrees/topics/names.doctree'
continue
# print("20140115 traversing", docname)
for ref in doc.traverse(addnodes.pending_xref):
if ref['reftype'] == 'doc':
other = docname_join(ref['refdoc'], ref['reftarget'])
else:
other = ref['reftarget']
if other == target:
found.add(ref['refdoc'])
# print("20140409 found", ref)
else:
# rows.add(ref['reftarget'])
rows.add(other)
# rows.add(repr(ref.attributes))
# row = []
# for h in headers:
# row.append(py2rst(getattr(ref, h, 'N/A')))
# rows.append(unicode(row))
if len(found) == 0:
s = """No documents found for target %r.""" % target
# s += """\nPending xrefs were %r.""" % rows
return s
entries = []
for refdoc in found:
mtime = path.getmtime(env.doc2path(refdoc))
entries.append((mtime, refdoc))
def f(a):
return a[0]
entries.sort(key=f)
entries.reverse()
import time
# from time import strftime
items = [':doc:`/%(doc)s` (%(time)s)' % dict(
time=time.ctime(e[0]),
doc=e[1]) for e in entries]
if 'debug' in self.options:
items.append("DEBUG: pending xrefs were %r." % rows)
return rstgen.ul(items)
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 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 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
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 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 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
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
def run(self):
env = self.state.document.settings.env
suffix = env.config.source_suffix
glob = 'glob' in self.options
# (title, ref) pairs, where ref may only be a document
# external links are forbidden, since we have no way of dating them
# 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)
ret = []
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 = 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(
'latest list glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
subnode = latest()
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['titlesonly'] = 'titlesonly' in self.options
#what does this do?
set_source_info(self, subnode)
wrappernode = nodes.compound(classes=['feed-latest-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
return ret
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 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(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
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=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 get_rst(self):
# return str(self.state.document.refnames)
env = self.state.document.settings.env
target = ' '.join(self.content).strip()
if not target:
target = env.temp_data['docname']
# print("20140409 target is %r" % target)
found = set()
rows = set()
# headers = 'children attributes \
# resolved referenced indirect_reference_name \
# tagname'.split()
for docname in env.found_docs:
if env.temp_data['docname'] == docname: # skip myself
continue
try:
doc = env.get_doctree(docname)
except Exception:
# 20140117 i had the following after a fab clean:
# File "/home/luc/pythonenvs/py27/local/lib/python2.7/site-packages/sphinx/environment.py", line 1077, in get_doctree
# f = open(doctree_filename, 'rb')
# IOError: [Errno 2] No such file or directory: u'/home/luc/hgwork/lino/docs/.build/.doctrees/topics/names.doctree'
continue
# print("20140115 traversing", docname)
for ref in doc.traverse(addnodes.pending_xref):
if ref['reftype'] == 'doc':
other = docname_join(ref['refdoc'], ref['reftarget'])
else:
other = ref['reftarget']
if other == target:
found.add(ref['refdoc'])
# print("20140409 found", ref)
else:
# rows.add(ref['reftarget'])
rows.add(other)
# rows.add(repr(ref.attributes))
# row = []
# for h in headers:
# row.append(py2rst(getattr(ref, h, 'N/A')))
# rows.append(unicode(row))
if len(found) == 0:
s = """No documents found for target %r.""" % target
# s += """\nPending xrefs were %r.""" % rows
return s
entries = []
for refdoc in found:
mtime = path.getmtime(env.doc2path(refdoc))
entries.append((mtime, refdoc))
def f(a):
return a[0]
entries.sort(key=f)
entries.reverse()
import time
# from time import strftime
items = [':doc:`/%(doc)s` (%(time)s)' % dict(
time=time.ctime(e[0]),
doc=e[1]) for e in entries]
if 'debug' in self.options:
items.append("DEBUG: pending xrefs were %r." % rows)
return rstgen.ul(items)
