如何包含位于模块中但位于 class 之外的 docstrings/comments 和 Sphinx 中的方法

Question

我的包中有一个 utils 模块。它由几个不需要实例化的杂项独立方法组成。

我想在此 utils 文件中放置一些通用的 comments/docstring，例如：

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

如上所示，文档字符串有一个 table 包括指向各个方法的链接。目前，我的 index.rst 有这部分包括 utils:

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

目前，我在文档中正确显示了各个方法的文档字符串，但没有模块的顶级文档字符串（在任何 class 或方法之外）。让狮身人面像包含上述内容的最佳方法是什么？

一个选项可能是将顶级文档字符串移到此文件之外，例如 index.rst 等。但我宁愿不这样做，而是将其保留在源文件中。

Answer 1

感谢 jonsharpe 的评论，并引导我找到正确的方法。

为了其他人将来参考，我基本上将文档字符串移到了文件的开头：

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

就是这样！一切正常。

如何包含位于模块中但位于 class 之外的 docstrings/comments 和 Sphinx 中的方法

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

python-2.7

python-sphinx

autodoc