Question

修改截至目前（Sphinx 1.4.9），似乎无法告诉Sphinx做我想做的事情（请参阅GitHub上的issue）。 Brecht Machiels的accepted answer以另一种方式解决了这个问题，直到有一天Sphinx能够这样做。

说明我试图用sphinx-apidoc记录一个Python项目。 Sphinx配置几乎是默认配置，我只包括'sphinx.ext.autodoc'。

它通常有效，但派生类不会像我期望的那样继承其超类的方法文档。

示例： 考虑一个名为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:

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

问题： 有没有办法告诉Sphinx采用没有装饰魔术的父方法文档，如this SO帖子中描述的每一种方法？

Answer 1

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

# -*- 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更好的解决方案，因为在派生类上调用help()时也可以这样做。

Python-Sphinx：来自超类

1 个答案: