在 Python Sphinx 中使用 automodule 不会显示变量和类属性

Question

我想知道为什么在 Sphinx 中使用 automodule 指令时我看不到类属性......即使属性有文档字符串。

与 Django 设置 CONSTANTS 相同，它们没有显示。

我用：

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

我将设置拆分为模块

设置

• _初始化_.py
• installed_apps.py
• 语言环境.py
• 数据库文件
• 缓存文件
• stage_stable.py
• stage_test.py
• stage_dev.py
• ...
• 模板.py

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

它适用于 Django，简化了设置修改和...不适用于 Sphinx。

Answer 1

docstrings 通常不适用于类属性，但是如果您将它放在字段之后，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"]. （该列表可能包含多个扩展名。）

[编辑：] 我以前在错误的地方有文档注释。与 docstring 不同，#:注释必须放在您要注释的字段之前。

[编辑：] 由于以上不是问题，这里有另一种可能性。您之后使用的模块或包.. 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目录。（我也将其解析为绝对路径，这样出现意外的可能性就会减少。）显然，您必须针对您的具体情况更改此设置。

我希望这能够帮到你。