You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
400 lines
14 KiB
400 lines
14 KiB
"""
|
|
sphinx.directives.other
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
:copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS.
|
|
:license: BSD, see LICENSE for details.
|
|
"""
|
|
|
|
import re
|
|
from typing import Any, Dict, List, cast
|
|
|
|
from docutils import nodes
|
|
from docutils.nodes import Element, Node
|
|
from docutils.parsers.rst import directives
|
|
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
|
|
from docutils.parsers.rst.directives.misc import Class
|
|
from docutils.parsers.rst.directives.misc import Include as BaseInclude
|
|
|
|
from sphinx import addnodes
|
|
from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
|
|
from sphinx.domains.changeset import VersionChange # NOQA # for compatibility
|
|
from sphinx.locale import _
|
|
from sphinx.util import docname_join, url_re
|
|
from sphinx.util.docutils import SphinxDirective
|
|
from sphinx.util.matching import Matcher, patfilter
|
|
from sphinx.util.nodes import explicit_title_re
|
|
|
|
if False:
|
|
# For type annotation
|
|
from sphinx.application import Sphinx
|
|
|
|
|
|
glob_re = re.compile(r'.*[*?\[].*')
|
|
|
|
|
|
def int_or_nothing(argument: str) -> int:
|
|
if not argument:
|
|
return 999
|
|
return int(argument)
|
|
|
|
|
|
class TocTree(SphinxDirective):
|
|
"""
|
|
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,
|
|
'name': directives.unchanged,
|
|
'caption': directives.unchanged_required,
|
|
'glob': directives.flag,
|
|
'hidden': directives.flag,
|
|
'includehidden': directives.flag,
|
|
'numbered': int_or_nothing,
|
|
'titlesonly': directives.flag,
|
|
'reversed': directives.flag,
|
|
}
|
|
|
|
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['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 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 = [] # type: 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:
|
|
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:
|
|
if excluded(self.env.doc2path(docname, None)):
|
|
message = 'toctree contains reference to excluded document %r'
|
|
else:
|
|
message = 'toctree contains reference to nonexisting document %r'
|
|
|
|
ret.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)
|
|
|
|
# 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
|
|
|
|
|
|
class Author(SphinxDirective):
|
|
"""
|
|
Directive to give the name of the author of the current document
|
|
or section. Shown in the output only if the show_authors option is on.
|
|
"""
|
|
has_content = False
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
final_argument_whitespace = True
|
|
option_spec = {} # type: Dict
|
|
|
|
def run(self) -> List[Node]:
|
|
if not self.config.show_authors:
|
|
return []
|
|
para = nodes.paragraph(translatable=False) # type: Element
|
|
emph = nodes.emphasis()
|
|
para += emph
|
|
if self.name == 'sectionauthor':
|
|
text = _('Section author: ')
|
|
elif self.name == 'moduleauthor':
|
|
text = _('Module author: ')
|
|
elif self.name == 'codeauthor':
|
|
text = _('Code author: ')
|
|
else:
|
|
text = _('Author: ')
|
|
emph += nodes.Text(text, text)
|
|
inodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
|
|
emph.extend(inodes)
|
|
|
|
ret = [para] # type: List[Node]
|
|
ret += messages
|
|
return ret
|
|
|
|
|
|
class SeeAlso(BaseAdmonition):
|
|
"""
|
|
An admonition mentioning things to look at as reference.
|
|
"""
|
|
node_class = addnodes.seealso
|
|
|
|
|
|
class TabularColumns(SphinxDirective):
|
|
"""
|
|
Directive to give an explicit tabulary column definition to LaTeX.
|
|
"""
|
|
has_content = False
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
final_argument_whitespace = True
|
|
option_spec = {} # type: Dict
|
|
|
|
def run(self) -> List[Node]:
|
|
node = addnodes.tabular_col_spec()
|
|
node['spec'] = self.arguments[0]
|
|
self.set_source_info(node)
|
|
return [node]
|
|
|
|
|
|
class Centered(SphinxDirective):
|
|
"""
|
|
Directive to create a centered line of bold text.
|
|
"""
|
|
has_content = False
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
final_argument_whitespace = True
|
|
option_spec = {} # type: Dict
|
|
|
|
def run(self) -> List[Node]:
|
|
if not self.arguments:
|
|
return []
|
|
subnode = addnodes.centered() # type: Element
|
|
inodes, messages = self.state.inline_text(self.arguments[0], self.lineno)
|
|
subnode.extend(inodes)
|
|
|
|
ret = [subnode] # type: List[Node]
|
|
ret += messages
|
|
return ret
|
|
|
|
|
|
class Acks(SphinxDirective):
|
|
"""
|
|
Directive for a list of names.
|
|
"""
|
|
has_content = True
|
|
required_arguments = 0
|
|
optional_arguments = 0
|
|
final_argument_whitespace = False
|
|
option_spec = {} # type: Dict
|
|
|
|
def run(self) -> List[Node]:
|
|
node = addnodes.acks()
|
|
node.document = self.state.document
|
|
self.state.nested_parse(self.content, self.content_offset, node)
|
|
if len(node.children) != 1 or not isinstance(node.children[0],
|
|
nodes.bullet_list):
|
|
reporter = self.state.document.reporter
|
|
return [reporter.warning('.. acks content is not a list', line=self.lineno)]
|
|
return [node]
|
|
|
|
|
|
class HList(SphinxDirective):
|
|
"""
|
|
Directive for a list that gets compacted horizontally.
|
|
"""
|
|
has_content = True
|
|
required_arguments = 0
|
|
optional_arguments = 0
|
|
final_argument_whitespace = False
|
|
option_spec = {
|
|
'columns': int,
|
|
}
|
|
|
|
def run(self) -> List[Node]:
|
|
ncolumns = self.options.get('columns', 2)
|
|
node = nodes.paragraph()
|
|
node.document = self.state.document
|
|
self.state.nested_parse(self.content, self.content_offset, node)
|
|
if len(node.children) != 1 or not isinstance(node.children[0],
|
|
nodes.bullet_list):
|
|
reporter = self.state.document.reporter
|
|
return [reporter.warning('.. hlist content is not a list', line=self.lineno)]
|
|
fulllist = node.children[0]
|
|
# create a hlist node where the items are distributed
|
|
npercol, nmore = divmod(len(fulllist), ncolumns)
|
|
index = 0
|
|
newnode = addnodes.hlist()
|
|
for column in range(ncolumns):
|
|
endindex = index + ((npercol + 1) if column < nmore else npercol)
|
|
bullet_list = nodes.bullet_list()
|
|
bullet_list += fulllist.children[index:endindex]
|
|
newnode += addnodes.hlistcol('', bullet_list)
|
|
index = endindex
|
|
return [newnode]
|
|
|
|
|
|
class Only(SphinxDirective):
|
|
"""
|
|
Directive to only include text if the given tag(s) are enabled.
|
|
"""
|
|
has_content = True
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
final_argument_whitespace = True
|
|
option_spec = {} # type: Dict
|
|
|
|
def run(self) -> List[Node]:
|
|
node = addnodes.only()
|
|
node.document = self.state.document
|
|
self.set_source_info(node)
|
|
node['expr'] = self.arguments[0]
|
|
|
|
# Same as util.nested_parse_with_titles but try to handle nested
|
|
# sections which should be raised higher up the doctree.
|
|
memo = self.state.memo # type: Any
|
|
surrounding_title_styles = memo.title_styles
|
|
surrounding_section_level = memo.section_level
|
|
memo.title_styles = []
|
|
memo.section_level = 0
|
|
try:
|
|
self.state.nested_parse(self.content, self.content_offset,
|
|
node, match_titles=True)
|
|
title_styles = memo.title_styles
|
|
if (not surrounding_title_styles or
|
|
not title_styles or
|
|
title_styles[0] not in surrounding_title_styles or
|
|
not self.state.parent):
|
|
# No nested sections so no special handling needed.
|
|
return [node]
|
|
# Calculate the depths of the current and nested sections.
|
|
current_depth = 0
|
|
parent = self.state.parent
|
|
while parent:
|
|
current_depth += 1
|
|
parent = parent.parent
|
|
current_depth -= 2
|
|
title_style = title_styles[0]
|
|
nested_depth = len(surrounding_title_styles)
|
|
if title_style in surrounding_title_styles:
|
|
nested_depth = surrounding_title_styles.index(title_style)
|
|
# Use these depths to determine where the nested sections should
|
|
# be placed in the doctree.
|
|
n_sects_to_raise = current_depth - nested_depth + 1
|
|
parent = cast(nodes.Element, self.state.parent)
|
|
for i in range(n_sects_to_raise):
|
|
if parent.parent:
|
|
parent = parent.parent
|
|
parent.append(node)
|
|
return []
|
|
finally:
|
|
memo.title_styles = surrounding_title_styles
|
|
memo.section_level = surrounding_section_level
|
|
|
|
|
|
class Include(BaseInclude, SphinxDirective):
|
|
"""
|
|
Like the standard "Include" directive, but interprets absolute paths
|
|
"correctly", i.e. relative to source directory.
|
|
"""
|
|
|
|
def run(self) -> List[Node]:
|
|
if self.arguments[0].startswith('<') and \
|
|
self.arguments[0].endswith('>'):
|
|
# docutils "standard" includes, do not do path processing
|
|
return super().run()
|
|
rel_filename, filename = self.env.relfn2path(self.arguments[0])
|
|
self.arguments[0] = filename
|
|
self.env.note_included(filename)
|
|
return super().run()
|
|
|
|
|
|
# Import old modules here for compatibility
|
|
from sphinx.domains.index import IndexDirective # NOQA
|
|
|
|
deprecated_alias('sphinx.directives.other',
|
|
{
|
|
'Index': IndexDirective,
|
|
},
|
|
RemovedInSphinx40Warning,
|
|
{
|
|
'Index': 'sphinx.domains.index.IndexDirective',
|
|
})
|
|
|
|
|
|
def setup(app: "Sphinx") -> Dict[str, Any]:
|
|
directives.register_directive('toctree', TocTree)
|
|
directives.register_directive('sectionauthor', Author)
|
|
directives.register_directive('moduleauthor', Author)
|
|
directives.register_directive('codeauthor', Author)
|
|
directives.register_directive('seealso', SeeAlso)
|
|
directives.register_directive('tabularcolumns', TabularColumns)
|
|
directives.register_directive('centered', Centered)
|
|
directives.register_directive('acks', Acks)
|
|
directives.register_directive('hlist', HList)
|
|
directives.register_directive('only', Only)
|
|
directives.register_directive('include', Include)
|
|
|
|
# register the standard rst class directive under a different name
|
|
# only for backwards compatibility now
|
|
directives.register_directive('cssclass', Class)
|
|
# new standard name when default-domain with "class" is in effect
|
|
directives.register_directive('rst-class', Class)
|
|
|
|
return {
|
|
'version': 'builtin',
|
|
'parallel_read_safe': True,
|
|
'parallel_write_safe': True,
|
|
}
|