sphinx-autodoc 忽略 conf.py 中的默认设置

Question

我们有一个Python项目，这样做是为了生成文档：

sphinx-apidoc --module-first -f -o source/ ../src

make html

在最近的 sphinx (6.1.3) 中，我们注意到一个问题。其中一个类有一个类变量，它是 Pandas 数据帧。该内容是在 init 函数之前从 CSV 文件中读取的，并且 Sphinx html 输出将整个表格包含在文档中。我相信发生这种情况是因为该表是无证成员，而 Sphinx 正在做它认为正确的事情。我尝试了很多修复方法，在黑暗中摸索。

sphinx-autodoc 默认创建第一个文件，如下所示：

.. automodule:: my.app
   :members:
   :undoc-members:
   :show-inheritance:

如果我手动编辑第一个文件，我可以阻止不良结果的发生。我认为“no-undoc-members 可以解决问题，但事实并非如此。但是，添加排除参数确实有效。

.. automodule:: my.app
   :members:
   :no-undoc-members:
   :show-inheritance:
   :exclude-members: form, form_long

“修复”的问题是 autodoc 每次都必须更新第一个文件，它会删除第一个手动编辑的文件。

我已经尝试过这些方法来改变自动文档行为。

1. 在 Python 源代码中添加类变量的文档字符串。如果我指定文档字符串，那么 Sphinx 将不会打印整个 Pandas 表，不是吗？如果我在成员变量（如

   #: blah

   ）之前指定或在

   """ blah """

   之后指定，它应该可以工作。没有帮助。

2. 在source/conf.py中添加以下内容：

autodoc_default_options = {
    'undoc-members': False,
    'exclude-members': 'form'
}

但是，将其添加到

conf.py

后，sphinx-autodoc似乎并没有注意到。它使用相同的旧第一个文件默认值。另一个问题是，即使使用了，它似乎也不允许我在

exclude-members

中写入多个成员。我的意思是，我不知道正确的格式，并且我尝试过的所有操作都会导致

make html

出现错误

如果您帮助我了解我做错了什么，请提前致谢。

Answer 1

正如@mzjn 所解释的，sphinx-apidoc 不读取conf.py 文件。我没有找到可靠的方法来更改

sphinx-apidoc

创建的 RST 文件的默认内容。

以下是我们如何处理未记录的类对象被打印到文档中的具体问题。这不会更改第一个文件本身，而是更改为 HTML 的转换。

make

进程确实会读取conf.py，我们可以在其中插入代码来阻止插入这些对象的表。

def skip_member(app, what, name, obj, skip, options):
    if name in ['map', 'map_long', 'vm_map']:
        return True
    else:
        return None

def setup(app):
    app.connect('autodoc-skip-member', skip_member)

此示例阻止了 3 个特定变量的文档，但如果您想阻止类中的所有变量，可以输入类名称。

我不知道为什么为那些以前未记录的字符串插入文档字符串没有效果。也不明白 conf.py 中的

autodoc_default_options

应该做什么（如果有的话）。这里的说明对我来说没有意义https://smobsc.readthedocs.io/en/stable/usage/extensions/autodoc.html

Answer 2

迟到总比不到好……

autodoc_default_options = {
"exclude-members": "set_transform_request,set_fit_request",

}