===================================================================================
:mod:`cloud_sptheme.ext.autodoc_sections` - support for ReST sections in docstrings
===================================================================================

.. module:: cloud_sptheme.ext.autodoc_sections
    :synopsis: 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 :samp:`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.
