使用Sphinx生成文档时继承类文档字符串

Question

在使用 Sphinx 生成文档时，我尝试从父类继承文档字符串。这是一个最小的重现：

@dataclass
class A():
    """
    Attributes:
        a:
            This is the variable 'a'
    """
    a: int = 0

@dataclass
class B(A):
    """
    Attributes:
        b:
            This is the variable 'b'
    """
    b: int = 0

我的

conf.py

看起来像这样：

import os
import sys
sys.path.insert(0, os.path.abspath('../test_config'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc.typehints']
autodoc_inherit_docstrings = True

这就是我的

.rst

文件的样子：

Classes
===================
.. autoclass:: test_config.A()

.. autoclass:: test_config.B()
   :members:
   :show-inheritance:
   :inherited-members:

这给了我：

但是，我仍然无法将

A

的文档字符串导入

B

。

类似的问题之前已经被问过here和here，但它们都使用了装饰器。由于超出这个问题范围的原因，我将不能能够使用装饰器。

我也在

autodoc_inherit_docstrings=True

中尝试了

conf.py

，但没有成功。

解决这个问题的最佳方法是什么？ Sphinx 不支持开箱即用吗？

谢谢！

Answer 1

我能够在 autodoc-process-docstring 的帮助下做到这一点，它已注册为自定义扩展。

类似这样的：

def modify_docstring(app, what, name, obj, options, lines):
    # Access the existing docstring
    original_docstring = "\n".join(lines)

    # Get the parent class docstring
    parent_docstring = ""
    if obj.__bases__:  # Check if the class has a parent
        parent_class = obj.__bases__[0]  # Assuming single inheritance
        parent_class_name = parent_class.__name__
        try:
            parent_docstring = parent_class.__doc__
        except AttributeError:
            pass  # Handle cases where parent has no docstring

    modified_docstring =  f"{original_docstring}{parent_docstring}"

    print(f"Modified Docstring: \n {modified_docstring}\n")

    # Update the lines with the modified docstring
    lines[:] = modified_docstring.splitlines()

# Connect the handler to the event
def setup(app):
    app.connect('autodoc-process-docstring', modify_docstring)
    return {'version': '0.1'}