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

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

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

I use:

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

我将设置分成模块

settings

• _init_.py
• 安装的应用程序.py
• 语言环境.py
• db.py
• cache.py
• stage_stable.py
• 阶段测试.py
• stage_dev.py
• ...
• 模板.py

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

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

文档字符串通常不适用于类属性，但如果将其放在字段后面，Sphinx 的 autodoc 扩展就可以。您还可以在字段之前使用这种特殊语法：

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

其他需要检查的事情是您是否具有列在中的 autodoc 扩展名conf.py文件。寻找extensions = ["sphinx.ext.autodoc"]。 （该列表可能包含多个扩展名。）

[编辑：] 我之前将文档注释放在了错误的位置。与文档字符串不同，#:评论必须走before您正在评论的领域。

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

我希望这可以帮助你。