automodule: support multiple module level docstrings
Currently, automodule directive has a limitation: it only supports a single module level docstring.
So if documentation requires any additional sectioning/symbol grouping, the only option is to move these add ons into .rst file and switch from automodule to much more labor intensive autofunction and autoclass and, of course, the documentation gets fragmented (between the source file and the .rst file) and you need an extra file (.rst)..
I think life would be simpler if automodule supported multiple docstrings (or perhaps, even have another directive just for that purpose)
This is a module. It provides 2 levels of functionality """
""" Foo functionality =================
Foo serves a very useful purpose """
def foo(): "doc for foo" return
""" Bar functionality =================
Bar is even more useful """
def bar(): "doc for bar" return
Notes and observations
Multiple docstrings imply that symbols should be ordered by source (so such support cann't be made the default behavior of autodoc).
Module level docstrings need to be identified somehow. One way would be to have an rst directive just for that purpose, e.g
This is a module level docstring """
Once multiple docstrings are supported, I would expect that a much bigger percentage of modules will be fully documentable with automodule. And in many cases there won't even be a need to create .rst files manually (they could be created by a script).