===================================================================================
: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

.. versionchanged:: 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 Cloud) to distinguish these special
object-description-level sections from the document-level ones, the section
elements are assigned two extra css classes: ``desc-section`` and :samp:`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.

