cloud_sptheme.ext.autodoc_sections
- support for ReST sections in docstrings¶
Overview¶
This Sphinx extension should be used in conjunction with the Autodoc extension. This extension allows docstrings (module, class, function, etc) to include ReST-style section headers (which normally cause problems if integrated into Sphinx documentation via Autodoc).
This extension detects all single-line (but not double-line) headers,
and turns them into a series of definition lists (<dl>
), with the header
name as the term (<dt>
), and the section’s content as the definition (<dd>
).
Internals¶
In order for Sphinx themes (like Cloud)
to distinguish these from regular definition lists,
the <dl>
elements generated by this extension are assigned
two css classes: nested-section
and nested-section-level
.
Depending on the theme, these may require additional styling rules.
Warning
This extension is currently somewhat fragile: it works reliably for the common cases, but may not behave properly given unexpected input.
Todo
This extension has a number of things which could be improved:
- Handle double-lined headers as well as single-lined ones
- Use Sphinx’s ReST parser, instead of the custom hack currently in place
- Instead of outputing definition lists; it should output proper paragraph markup,
with
<h4/5/6>
headings. - Subsections should be included in Sphinx’s indexing.