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.