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 create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# Ensure configuration file exists.
conf_file = os.path.join(tmpdir, "conf.py")
with open(conf_file, "w", encoding="utf-8") as f:
f.write(CONF_PY)
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
kwds = {}
state = mock.Mock()
state.document.settings.tab_width = 8
kwds["state"] = state
yield DocumenterBridge(
app.env, LoggingReporter(''), Options(), 1, **kwds)
def create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# Ensure configuration file exists.
conf_file = os.path.join(tmpdir, "conf.py")
with open(conf_file, "w", encoding="utf-8") as f:
f.write(CONF_PY)
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
# Backwards compatibility hack: for now, we need to be compatible
# with both Sphinx < 2.1 (whose DocumenterBridge doesn't take
# a state argument) and Sphinx >= 2.3 (which warns if the state
# isn't passed). Eventually we should be able to drop support
# for Sphinx < 2.1.
kwds = {}
if sphinx.version_info >= (2, 1):
state = mock.Mock()
state.document.settings.tab_width = 8
kwds["state"] = state
yield DocumenterBridge(
app.env, LoggingReporter(''), Options(), 1, **kwds)
def do_autodoc(app, objtype, name, options={}):
doccls = app.registry.documenters[objtype]
docoptions = process_documenter_options(doccls, app.config, options)
bridge = DocumenterBridge(app.env, LoggingReporter(''), docoptions, 1)
documenter = doccls(bridge, name)
documenter.generate()
return bridge.result
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 documenter_bridge(sphinx_state):
"""
Common documenter bridge used for creating directives. This only provides
what's been deemed necessary for testing so anything extra should be
added as needed.
Yields:
DocumenterBridge for creating documenters.
"""
yield DocumenterBridge(sphinx_state.env, None, None, None, state=sphinx_state)
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 run(self):
reporter = self.state.document.reporter
try:
source, lineno = reporter.get_source_and_line(self.lineno) # type: ignore
except AttributeError:
source, lineno = (None, None)
logger.debug('[sphinxcontrib-matlabdomain] %s:%s: input:\n%s', source, lineno, self.block_text)
# look up target Documenter
objtype = self.name.replace('auto', '') # Removes auto
doccls = self.env.app.registry.documenters[objtype]
# process the options with the selected documenter's option_spec
try:
documenter_options = process_documenter_options(doccls, self.config, self.options)
except (KeyError, ValueError, TypeError) as exc:
# an option is either unknown or has a wrong type
logger.error('An option to %s is either unknown or has an invalid value: %s' %
(self.name, exc), location=(source, lineno))
return []
# generate the output
if version_info[0] >= 2:
params = DocumenterBridge(self.env, reporter, documenter_options, lineno, self.state)
else:
params = DocumenterBridge(self.env, reporter, documenter_options, lineno)
documenter = doccls(params, self.arguments[0])
documenter.generate(more_content=self.content)
if not params.result:
return []
logger.debug('[sphinxcontrib-matlabdomain] output:\n%s', '\n'.join(params.result))
# record all filenames as dependencies -- this will at least
# partially make automatic invalidation possible
for fn in params.filename_set:
self.state.document.settings.record_dependencies.add(fn)
result = parse_generated_content(self.state, params.result, documenter)
return result
def do_autodoc(app, objtype, name, options=None):
if options is None:
options = {}
app.env.temp_data.setdefault("docname", "index") # set dummy docname
doccls = app.registry.documenters[objtype]
docoptions = process_documenter_options(doccls, app.config, options)
state = Mock()
state.document.settings.tab_width = 8
bridge = DocumenterBridge(app.env, LoggingReporter(""), docoptions, 1,
state)
documenter = doccls(bridge, name)
documenter.generate()
return bridge.result
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 __init__(self,
directive: DocumenterBridge,
name: str,
indent: str = "") -> None:
"""
Override the :attr:`directive` so that some post processing can be
performed in :meth:`generate`
"""
super().__init__(directive, name, indent)
self._original_directive = self.directive
self.directive = DocumenterBridge(
self.directive.env,
self.directive.reporter,
self.directive.genopt,
self.directive.lineno,
self.directive.state,
)
def run(self) -> List[Node]:
self.bridge = DocumenterBridge(self.env, self.state.document.reporter,
Options(), self.lineno, self.state)
names = [
x.strip() 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 "caption" in self.options:
logger.warning(__(
"A captioned autosummary requires :toctree: option. ignored."),
location=nodes[-1])
return nodes
def create_directive(self):
"""
Helper function to create a a "directive" suitable
for instantiating the TraitDocumenter with, along with resources
to support that directive, and clean up the resources afterwards.
Returns
-------
contextmanager
A context manager that returns a DocumenterBridge instance.
"""
with self.tmpdir() as tmpdir:
# The configuration file must exist, but it's okay if it's empty.
conf_file = os.path.join(tmpdir, "conf.py")
with io.open(conf_file, "w", encoding="utf-8"):
pass
app = SphinxTestApp(srcdir=path(tmpdir))
app.builder.env.app = app
app.builder.env.temp_data["docname"] = "dummy"
yield DocumenterBridge(app.env, LoggingReporter(''), Options(), 1)
def run(self):
reporter = self.state.document.reporter
try:
source, lineno = reporter.get_source_and_line(self.lineno)
except AttributeError:
source, lineno = (None, None)
# look up target Documenter
objtype = self.name[4:-4] # strip prefix (auto-) and suffix (-summ).
doccls = self.env.app.registry.documenters[objtype]
self.options['autosummary-force-inline'] = "True"
self.options['autosummary'] = "True"
if 'no-members' not in self.options:
self.options['members'] = ""
# process the options with the selected documenter's option_spec
try:
documenter_options = process_documenter_options(doccls, self.config,
self.options)
except (KeyError, ValueError, TypeError) as exc:
# an option is either unknown or has a wrong type
logger.error(
'An option to %s is either unknown or has an invalid '
'value: %s', self.name, exc,
location=(self.env.docname, lineno))
return []
# generate the output
params = DocumenterBridge(self.env, reporter, documenter_options,
lineno, self.state)
documenter = doccls(params, self.arguments[0])
documenter.add_autosummary()
node = nodes.paragraph()
node.document = self.state.document
self.state.nested_parse(params.result, 0, node)
return node.children
def autosummary_documenter(self):
"""Returns the AutosummaryDocumenter subclass that can be used"""
try:
return self._autosummary_documenter
except AttributeError:
pass
objtype = self.name[4:]
env = self.state.document.settings.env
if sphinx_version < [1, 7]:
doc_class = self._registry[objtype]
params = self
else:
reporter = self.state.document.reporter
try:
lineno = reporter.get_source_and_line(self.lineno)[1]
except AttributeError:
lineno = None
doc_class = get_documenters(self.env.app)[objtype]
args = (self.state, ) if sphinx_version >= [2, 1] else ()
params = DocumenterBridge(
env, reporter,
process_documenter_options(doc_class, env.config,
self.options),
lineno, *args)
documenter = doc_class(params, self.arguments[0])
if hasattr(documenter, 'get_grouped_documenters'):
self._autosummary_documenter = documenter
return documenter
# in case the has been changed in the registry, we decide manually
if objtype == 'module':
documenter = AutoSummModuleDocumenter(params, self.arguments[0])
elif objtype == 'class':
documenter = AutoSummClassDocumenter(params, self.arguments[0])
else:
raise ValueError(
"Could not find a valid documenter for the object type %s" % (
objtype))
self._autosummary_documenter = documenter
return documenter