In Sphinx, how to include docstrings/comments located in a module, but outside of class and methods

问题

I have a utils module in my package. It consists of several misc standalone methods that do not require instantiation.

I would like to place some generic comments/docstring inside this utils file, such as:

import os
import json

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

As seen above, the docstring has a table including links to the individual methods. Currently, my index.rst has this part to include utils:

Utilities
============
.. automodule:: packagename.utils
   :members:

Currently, I get the docstrings of the individual methods properly displayed in the documentation, but not the top-level docstring of the module (outside of any class or method). What is the best way to have have sphinx include the above?

One option might be to move the top-level docstring outside of this file, such as to index.rst etc. But I would prefer not doing this, and retain it within the source file.

回答1:

Thanks to jonsharpe for his comment, and leading me to the proper way of doing this.

For future reference by others, I basically moved the docstrings to the start of the file:

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

import os
import json

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

And that's it! Everything works.

来源：https://stackoverflow.com/questions/47071959/in-sphinx-how-to-include-docstrings-comments-located-in-a-module-but-outside-o