Follow PEP 257 docstring conventions

[not-my-profile]

PEP 257 establishes conventions for docstrings, in particular:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

Sphinx currently violates that convention by formatting its module docstrings as follows:

"""
    sphinx.builders
    ~~~~~~~~~~~~~~~

    Builder superclass for all builders.

    :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
"""

Note that the summary is not in the first line but after a heading and a blank line. This is problematic because when e.g. browsing the Sphinx API via Pydoctor, Pydoctor just shows the headings (since it assumes the PEP 257 convention):

So it would be great if Sphinx could follow PEP 257 by removing such headings from its module docstrings.

[AA-Turner]

I'd be against this (internal consistency is more important) -- have you spoken to the PyDoctor project about adding support for basic parsing reST parsing/recognition?

A

[not-my-profile]

I don't get "internal consistency" as an argument. I am proposing to change this everywhere in the sphinx codebase, so after the change it would still be consistent internally.

PyDoctor was just an example ... the point of such conventions is that following them provides interoperability with many tools.

[AA-Turner]

I appreciate the convention -- equally reST is a convention, and this project has maintained the convention of using reST headers in docstrings since the first tracked commit with files (d60ca8d).

Changing the module docstrings might be a valid & useful thing to do, I am personally less convinced by requests to do something just as it is documented in a PEP as a convention (although that adds weight to an argument).

As a series of questions that might prompt the rationale behind this suggestion:

• What does the inconvinence in using a tool such as PyDocter cause?
• What can't you do currently?
• Does the Sphinx documentation not solve what you're trying to do?

A

[tk0miya]

+1 for the removal. AFAIK, our document do not use the headings of our module docstrings to generate our document. Additionally, all headings are as same as their module name. So I feel they're redundant. I guess they will not help developers.

[not-my-profile]

@AA-Turner Pydoctor was just an example ... to give you another example, the Python standard library comes with pydoc, and e.g. running python -m pydoc sphinx.addnodes (or running help(sphinx.addnotes) in an interactive session) shows the following:

Help on module sphinx.addnodes in sphinx:

NAME
    sphinx.addnodes

DESCRIPTION
    sphinx.addnodes
    ~~~~~~~~~~~~~~~
    
    Additional docutils nodes.
    
    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.

Note the duplicate heading under DESCRIPTION.

[AA-Turner]

#10212 is an attempt to make module docstrings conform to the strictures of PEP 257, as an alternative to #10208.

cc @not-my-profile for interest.

A