automodule: support multiple module level docstrings

Anonymous avatarAnonymous 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 (3)

  1. Georg Brandl
    • 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

    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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.