I know this is a very old thread, but wanted to respond to it anyways. A few years ago I found this thread trying solve the same problem. I ended up coding my own Sphinx extension which monkeypatches Sphinx so that sections nested inside docstrings are supported.
It's distributed at part of a package containing a custom sphinx theme, but the extension should be usuable independantly of the theme (and I'm certainly open to contributing it back to Sphinx if there's interest). The documentation is at https://pythonhosted.org/cloud_sptheme/lib/cloud_sptheme.ext.autodoc_sections.html, and the source code for the extension itself can be viewed at https://bitbucket.org/ecollins/cloud_sptheme/src/tip/cloud_sptheme/ext/autodoc_sections.py. The only drawbacks to this extension are 1) it may require some custom css styling in order for docstring sections to layout in a desirable manner, 2) sections within docstrings aren't currently added into the TOC, and 3) it works through extensive monkeypatching and callstack inspection of sphinx. Hopefully someone will still find it helpful, at least as a starting point for a more proper implementation :) - Eli On Saturday, October 3, 2009 at 2:43:08 PM UTC-4, Oben wrote: > > Hi all, > > I have a question on the autodoc extension. > > It seems sections are not allowed in docstrings, at least I get this > error messages when I use the autodoc extensions for modules, > classes, ... which contain a section heading: > Unexpected section title or transition > Is this an error on my side or are sections not allowed by design? > > In my workflow I really prefer to have all documentation in the source > file and thus would benefit from sections in docstrings. > > Thanks, > Oben > -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
