在Sphinx中自动作文单个模块属性

Question

假设我在一个Python模块中记录了一个变量，像这样：

some_random_name = 'whatever'
"""The random whatever variable"""

我可以在我的.rst文件中只为这个单独的变量包含自动文档，而不把整个模块的__doc__字符串也带上去，生成文档输出吗？

我试过

.. automodule: themodule
   :members: some_random_name

但是这样不仅把__doc__字符串也带上了，而且也没有显示some_random_name的自动文档。

Answer 1

我无法重现关于模块属性文档的问题。对我来说，这一切都正常。你是否在你的模块中有一个 __all__ 变量，它的值里没有 some_random_name 呢？Sphinx 在查找成员时会考虑 __all__。

可以通过拦截 autodoc-process-docstring 事件来移除模块的文档字符串。这里有个示例（把代码添加到 conf.py 中）：

import inspect

def remove_mod_docstring(app, what, name, obj, options, lines):
    """Erase module docstring in-place"""  
    if inspect.ismodule(obj):
        for i in xrange(len(lines)):
            lines[i] = ''

def setup(app):
    app.connect('autodoc-process-docstring', remove_mod_docstring)