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.