cloud_sptheme.ext.autodoc_sections
- support for ReST sections in docstrings¶
Changed in version 1.7: Drastically revamped how extension works, as well as the DOM / css styles it generates. Themes relying on the previous output structure may need to be updated (the css classes were changed, to allow simulatenous styling of both old and new versions).
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).
Internals¶
This extension does an extensive amount of monkeypatching within Sphinx and Docutils. While this allows it to leverage Docutil’s native RST parser (rather than implement it’s own), this does mean it may be more fragile if any of the internals change. Please report any bugs.
In order for Sphinx themes (like this one) to distinguish document-level sections
from the special object-description sections generated by this extension, it assigns
two extra css classes to the sections it generates: desc-section
and desc-section-level
.
Additionally, the header element of each section is assigned the css class section-header
.
Depending on the theme, these may require additional styling rules.
Todo
This extension has a few things which could be improved:
- Subsections should be included in Sphinx’s indexing.