使用Sphinx的automodule时，变量和类属性不显示

Question

我在想，为什么在使用Sphinx的automodule指令时，看不到类的属性……即使这些属性有文档字符串。

同样的情况也发生在Django的设置常量上，它们也没有显示出来。

我使用的是：

.. automodule:: settings
   :members:
   :show-inheritance:
   :undoc-members:

我把设置分成了多个模块：

settings

• _init_.py
• installed_apps.py
• locale.py
• db.py
• cache.py
• stage_stable.py
• stage_test.py
• stage_dev.py
• ...
• templates.py

在__init__.py文件中，我从其他文件导入所有内容，并选择我当前的阶段。

这样做在Django中是有效的，简化了设置的修改……但在Sphinx中却不行。

Answer 1

文档字符串通常不适用于类的属性，但如果你把它放在字段后面，Sphinx的autodoc扩展可以做到这一点。你也可以使用这种特殊的语法，把它放在字段前面：

#: Documentation for my_field.  You can
#: use one or more lines as well.
my_field = "something"

另外要检查的是，你在conf.py文件中是否列出了autodoc扩展。查找extensions = ["sphinx.ext.autodoc"]。这个列表可能包含多个扩展。

[编辑:] 我之前把文档注释放错地方了。与文档字符串不同，#:注释必须放在你要注释的字段之前。

[编辑:] 既然上面不是问题，那还有另一种可能性。你在.. automodule::后面使用的模块或包必须对你的文档可访问。这意味着你需要确保将它的位置添加到你的Python路径中。我的项目是这样设置的：

my_project/
    package/
        __init__.py
        ...
    doc/
        build/
            ...
        source/
            conf.py
            ...

在这种情况下，我需要将/my_package添加到Python路径中，以便可以访问package。为此，我确保在我的conf.py文件顶部添加了这个：

import sys, os   # I believe conf.py already imports sys,
import os.path   # os, and os.path.  But just in case, I
                 # list it here.

sys.path.insert(0, os.path.abspath(os.path.join('..','..')))

这实际上将./../..添加到Python路径中，从我的例子中的conf.py来看，这就是my_project目录。（我还将其解析为绝对路径，以减少意外情况的可能性。）显然，你需要根据你的具体情况进行更改。

希望这对你有帮助。