def test_doc(self, struct, expected_doc, sphinx_state):
"""
Tests the restructured text output returned by the directive.
"""
directive = AutodocDirective(
"autocstruct",
[struct],
# Members of structs should be visible even with no private members.
# I.e. if the struct is visible all of it is.
{
"members": None,
"no-private-members": None
},
None,
None,
None,
None,
sphinx_state,
None,
)
output = directive.run()
# First item is the index entry
assert 2 == len(output)
body = output[1]
# For whatever reason the as text comes back with double spacing, so we
# knock it down to single spacing to make the expected string smaller.
assert body.astext().replace("\n\n", "\n") == dedent(expected_doc)
def test_custom_napoleon_section(self, sphinx_state):
"""
Tests the restructured text output returned by the directive.
"""
custom_napoleon_section = """\
void *custom_napoleon_section(char first_param, int second_param)
A function using a custom napoleon section that doesn't exist in this
package.
Parameters
first_param -- A parameter to document
second_param -- Why not"""
sphinx_state.env.app.connect("autodoc-process-docstring",
process_autodoc_docstring)
directive = AutodocDirective(
"autocfunction",
["functions.c::custom_napoleon_section"],
{"members": None},
None,
None,
None,
None,
sphinx_state,
None,
)
output = directive.run()
# First item is the index entry
assert 2 == len(output)
body = output[1]
# For whatever reason the as text comes back with double spacing, so we
# knock it down to single spacing to make the expected string smaller.
assert body.astext().replace("\n\n",
"\n") == dedent(custom_napoleon_section)
def test_fail_module_load(self, sphinx_state):
"""
Test that a warning is raised when unable to find the module to
document
"""
directive = AutodocDirective(
"autocmodule",
["non_existent.c"],
{"members": None},
None,
10,
None,
None,
sphinx_state,
None,
)
output = directive.run()
assert output == []
warnings = sphinx_state.env.app._warning.getvalue()
messages = ("Unable to find", "non_existent.c")
for message in messages:
assert message in warnings
def test_incorrectly_specified_variable_causes_warning(self, sphinx_state):
"""
Test that when a directive string is for an unparsable variable name
a warning is thrown.
"""
directive = AutodocDirective(
"autocdata",
["example.c::unparseable-kabab"],
{"members": None},
None,
None,
None,
None,
sphinx_state,
None,
)
output = directive.run()
warnings = sphinx_state.env.app._warning.getvalue()
messages = ("invalid signature for autocdata", )
for message in messages:
assert message in warnings
assert [] == output
def test_pre_parsing(sphinx_state):
"""
Tests the restructured text output returned by the directive.
"""
sphinx_state.env.app.connect("c-autodoc-pre-process", pre_parser)
directive = AutodocDirective(
"autocdata",
["variables.c::compilation_db_define"],
{"members": None},
None,
None,
None,
None,
sphinx_state,
None,
)
output = directive.run()
# First item is the index entry
assert 2 == len(output)
body = output[1]
# For whatever reason the as text comes back with double spacing, so we
# knock it down to single spacing to make the expected string smaller.
assert dedent(new_contents_int) == body.astext().replace("\n\n", "\n")
def run(self):
"""Run method for the directive"""
options_save = self.options.copy()
doc_nodes = AutodocDirective.run(self)
self.options.update(options_save)
if 'autosummary' not in self.options:
return doc_nodes
try:
self.env = self.state.document.settings.env
except AttributeError:
pass # is set automatically with sphinx >= 1.8.0
if sphinx_version < [2, 0]:
self.warnings = []
self.result = ViewList()
documenter = self.autosummary_documenter
grouped_documenters = documenter.get_grouped_documenters()
nested = 'autosummary-no-nesting' not in self.options
summ_nodes = self.autosumm_nodes(documenter, grouped_documenters,
nested)
dn = summ_nodes.pop(documenter.fullname)
if self.name == 'automodule':
doc_nodes = self.inject_summ_nodes(doc_nodes, summ_nodes)
# insert the nodes directly after the paragraphs
if self.name == 'autoclass':
for node in dn[::-1]:
self._insert_after_paragraphs(doc_nodes[1], node)
dn = []
elif self.name == 'automodule':
# insert table before the documentation of the members
istart = 2 if 'noindex' not in self.options else 0
# if we have a title in the module, we look for the section
if (len(doc_nodes) >= istart + 1
and isinstance(doc_nodes[istart], nodes.section)):
others = doc_nodes[istart]
istart = 2 # skip the title
else:
others = doc_nodes
found = False
if len(others[istart:]) >= 2:
for i in range(istart, len(others)):
if isinstance(others[i], sphinx.addnodes.index):
found = True
break
if found:
for node in dn[::-1]:
others.insert(i, node)
dn = []
if sphinx_version < [2, 0]:
return self.warnings + dn + doc_nodes
else:
return dn + doc_nodes
def test_doc(self, type_, expected_doc, sphinx_state):
"""
Tests the restructured text output returned by the directive.
"""
directive = AutodocDirective(
"autoctype",
[type_],
{"members": None},
None,
None,
None,
None,
sphinx_state,
None,
)
output = directive.run()
# First item is the index entry
assert 2 == len(output)
body = output[1]
# For whatever reason the as text comes back with double spacing, so we
# knock it down to single spacing to make the expected string smaller.
assert body.astext().replace("\n\n", "\n") == dedent(expected_doc)