在 Sphinx autodoc 中使用模块文档字符串

Question

In the Sphinx autodoc generated documentation I want kind of an introduction text for each module. I my logic this is related to the modules docstring. But Sphinx ignores it because it appears nowhere in the generated HTML files.

# -*- coding: utf-8 -*-
import mypackage

"""This is the modules docstring.
"""


def bar(bar):
    """
    This is the function named bar.

    Parameters:
        bar (str): Just a parameter.

    Returns:
        str: Just an 'a'.
    """
    mypackage.foo(bar)
    return('a')

I am not sure if this is in the concept of Sphinx or if Sphinx want me to realize that another way.

But the point is I do not want to but documentation in the rst -files. Every documentation content should come from the docstrings in the py -files themselfs.

Answer 1

Based on @mzjn 's comment.

The module docstring must be the first thing in the module (before import statements). See also: https://stackoverflow.com/a/48682589/407651

So it must be

# -*- coding: utf-8 -*-
"""This is the modules docstring.
"""
import mypackage

def bar(bar):
# ...
´´´