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

Question

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

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

我使用：

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

我将设置拆分为模块

settings

• _init
• _.pyinstalled_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 目录。 （我还将其解析为绝对路径，这样出现意外的可能性就会减少。）显然，您必须根据您的具体情况更改此设置。

我希望这对你有帮助。