python - 在 Python Sphinx 中使用自动模块不显示变量和类属性

Question

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

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

我使用:

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

我将设置拆分为模块

设置

• _初始化_.py
• installed_apps.py
• 语言环境.py
• 数据库文件
• 缓存.py
• stage_stable.py
• 阶段测试.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"]。 (该列表可能包含多个扩展名。)

[edit:] 我以前在错误的地方有文档注释。与文档字符串不同，#: 注释必须位于您要注释的字段之前。

[edit:] 由于以上不是问题，这里有另一种可能性。您在 .. 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 目录。 (我还将其解析为绝对路径，这样出现意外的可能性就会减少。)显然，您必须针对您的具体情况进行更改。

希望对您有所帮助。