gpt4 book ai didi

Python-Sphinx:来自父类(super class)的 "inherit"方法文档

转载 作者:太空狗 更新时间:2023-10-30 01:12:45 25 4
gpt4 key购买 nike

编辑:截至目前(Sphinx 1.4.9)似乎没有办法告诉 Sphinx 做我想做的事(参见 GitHub 上的 issue)。 accepted answer Brecht Machiels 以另一种方式解决了这个问题,直到有一天 Sphinx 可以这样做。

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

它通常可以工作,但派生类不会像我期望的那样继承其父类(super class)的方法文档。

示例:考虑一个名为 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 的文档字符串是空的。

问题:this 中所述,有没有办法告诉 Sphinx 在没有装饰器魔法的情况下获取父方法文档? SO 为每一种方法发布?

最佳答案

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

# -*- 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:来自父类(super class)的 "inherit"方法文档,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/40508492/

25 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com