如何告诉 sphinx-apidoc 覆盖特定 Python 类的选项？

Question

我遇到了https://github.com/sphinx-doc/sphinx/issues/8664中描述的问题，其中我有一个带有类型注释成员和谷歌风格属性的类：pydocs，例如：

class Foo(Bar):
      """Something something.

      Attributes:
           baz: A handy thing.
      """

      baz: str

当我对我的项目运行

sphinx-apidoc

时，我得到：

docstring of my_project.Foo.baz:1:duplicate object description of my_project.Foo.baz, other instance in source/my_project, use :noindex: for one of them

我了解到这本质上是因为

:undoc-members:

自动设置了

sphinx-apidoc

。这是一个有用的设置（因为我并不总是记录所有成员），但在这种情况下，它与我记录的成员冲突。除非有一个优雅的解决方案，我可以在其中指定如何解决此类冲突，否则我很乐意告诉

autodoc

为我的班级

:undoc-members:

关闭

Foo

。

有什么办法可以做到这一点，例如通过支持更改特定成员选项的事件？

Answer 1

我找到了解决我的问题的方法 - 不是真正的解决方案，而是作为答案发布，因为它足以满足我的短期需求并且可能对其他人也有帮助：

由于我使用

napoleon

扩展从Google 风格的文档字符串生成API 文档，我发现我可以在Sphinx

[napoleon_use_ivar][1]

中将

True

设置为

conf.py

以避免我的示例引发的冲突问题。这是

conf.py

的相关片段：

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_rtd_theme",
]
napoleon_google_docstring = True  # Enable parsing of Google-style pydocs.
napoleon_use_ivar = True  # to correctly handle Attributes header in class pydocs

效果是告诉 Napoleon 将 Attributes: 标头视为描述实例变量。这有效地避免了冲突，尽管生成的文档现在确实列出了每个属性（“变量”）两次（以不同的方式）——所以这不是一个理想的解决方案，但至少它避免了（无法抑制的）警告。