Issue #442 wontfix

automodule: support multiple module level docstrings

Anonymous created an issue

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)



""" Overview

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

""".. moddocstring::

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).

Comments (4)

  1. Georg Brandl repo owner
    • changed status to open

    Hmm. This kind of "docstrings" (it's not a real docstring as seen by Python) is not very common, and I don't know if I would like to see them becoming common.

    Will have to think about this.

  2. Anonymous

    Yes, it's not really a "docstring" in the normal sense of the word. But then normal python docstings have never been that useful for good documentation ;-).

    I do think that this functionality provides a major convenience for the documentation writer (as it allows to keep docs in the source in a much large number of cases and docs in the source are much easier to maintain in general).

    Btw, what I'm suggesting is not really new: e.g. perldoc has always allowed docs to be interleaved with the code (I used it myself and think that it's very useful).

  3. Georg Brandl repo owner

    Thinking more about this, I came to the conclusion that this really is more of a literal programming style than I feel comfortable with. There are several tools for literal programming that should fit it better.

    Otherwise, sprinkling strings that are not docstrings around the source is not good practice right now, and I don't want Sphinx to make it popular.

  4. Log in to comment