Python-Sphinx: "inherit" 来自超类的方法文档

Question

编辑： 截至目前（Sphinx 1.4.9）似乎没有办法告诉 Sphinx 做我想做的事（见 Brecht Machiels 的 issue on GitHub). The 以另一种方式解决了这个问题，直到 Sphinx 可以这样做天.

描述： 我正在尝试使用 sphinx-apidoc 记录一个 Python 项目。 Sphinx 配置几乎是默认的，我只是包含了 'sphinx.ext.autodoc'.

它一般有效，但派生的类没有像我期望的那样继承它们的 super类的方法文档。

示例： 考虑一个名为 project 的非常简约的 Python 包。除了一个空的 __init__.py 它只包含一个文件（base.py，见下文）

# -*- coding: utf-8 -*
import abc


class Superclass(object):
    """The one to rule them all"""

    @abc.abstractmethod
    def give(self, ring):
        """Give out a ring"""
        pass


class Derived(Superclass):
    """Somebody has to do the work"""

    def give(self, ring):
        print("I pass the ring {} to you".format(ring))

运行 sphinx-apidoc (sphinx-apidoc -o apidoc project -f) 生成以下文件：

apidoc/modules.rst

project
=======

.. toctree::
   :maxdepth: 4

   project

apidoc/project.rst

project package
===============

Submodules
----------

project.base module
-------------------

.. automodule:: project.base
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

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

在默认的 index.rst 中包含 apidoc/modules.rst，然后是 make html，为类及其方法生成基本的 html 文档。不幸的是，Derived.give 的文档字符串是空的。

问题： 有没有办法告诉 Sphinx 在没有装饰器魔法的情况下获取父方法文档，如 this SO post 中所述，对于每个方法？

Answer 1

您可以通过为抽象基础 class 使用元class 来自动管理文档字符串。以下是此类元class 的一个非常基本的实现。它需要扩展以正确处理多个基本 classes 和极端情况。

# -*- coding: utf-8 -*
import abc


class SuperclassMeta(type):
    def __new__(mcls, classname, bases, cls_dict):
        cls = super().__new__(mcls, classname, bases, cls_dict)
        for name, member in cls_dict.items():
            if not getattr(member, '__doc__'):
                member.__doc__ = getattr(bases[-1], name).__doc__
        return cls


class Superclass(object, metaclass=SuperclassMeta):
    """The one to rule them all"""

    @abc.abstractmethod
    def give(self, ring):
        """Give out a ring"""
        pass


class Derived(Superclass):
    """Somebody has to do the work"""

    def give(self, ring):
        print("I pass the ring {} to you".format(ring))

这甚至比让 Sphinx 这样做更好，因为这在派生的 classes 上调用 help() 时也有效。

Python-Sphinx: "inherit" 来自超类的方法文档

Python-Sphinx: "inherit" method documentation from superclass

python

inheritance

docstring

python-sphinx