温馨提示:本文翻译自stackoverflow.com,查看原文请点击:python - Sphinx

python - 狮身人面像

发布于 2020-03-30 21:24:23

我有一些彼此继承的类。所有类都包含相同的方法(我们称它为mymethod),从而子级将覆盖基类方法。我想mymethod使用sphinx所有类生成文档

假设mymethod有一个论点myargument对于基础方法和继承方法,此参数具有相同的类型和含义。为了最大程度地减少冗余,我myargument只想为基类编写文档,然后文档插入子方法的文档中。也就是说,我不想只对基类进行简单引用,而是在生成文档时动态地插入文本。

能做到吗?怎么样?

请在下面找到一些说明问题的代码。

class BaseClass
    def mymethod(myargument):
        """This does something

        Params
        ------
        myargument : int
            Description of the argument

        """
        [...]


class MyClass1(BaseClass):
    def mymethod(myargument):
        """This does something

        Params
        ------
        [here I would like to insert in the description of ``myargument`` from ``BaseClass.mymethod``]
        """

        BaseClass.mymethod(myargument)
        [...]

class MyClass2(BaseClass):
    def mymethod(myargument, argument2):
        """This does something

        Params
        ------
        [here I would like to insert in the description of ``myargument`` in ``BaseClass.mymethod``]
        argument2 : int
            Description of the additional argument

        """

        BaseClass.mymethod(argument)
        [...]


查看更多

提问者
Samufi
被浏览
21
Jordan Brière 2020-01-31 17:19

可能不太理想,但是也许您可以使用装饰器来扩展文档字符串。例如:

class extend_docstring:
    def __init__(self, method):
        self.doc = method.__doc__

    def __call__(self, function):
        if self.doc is not None:
            doc = function.__doc__
            function.__doc__ = self.doc
            if doc is not None:
                function.__doc__ += doc
        return function


class BaseClass:
    def mymethod(myargument):
        """This does something

        Params
        ------
        myargument : int
            Description of the argument
        """
        [...]


class MyClass1(BaseClass):
    @extend_docstring(BaseClass.mymethod)
    def mymethod(myargument):
        BaseClass.mymethod(myargument)
        [...]

class MyClass2(BaseClass):
    @extend_docstring(MyClass1.mymethod)
    def mymethod(myargument, argument2):
        """argument2 : int
            Description of the additional argument
        """

        BaseClass.mymethod(argument)
        [...]


print('---BaseClass.mymethod---')
print(BaseClass.mymethod.__doc__)
print('---MyClass1.mymethod---')
print(MyClass1.mymethod.__doc__)
print('---MyClass2.mymethod---')
print(MyClass2.mymethod.__doc__)

结果:

---BaseClass.mymethod---
This does something

        Params
        ------
        myargument : int
            Description of the argument

---MyClass1.mymethod---
This does something

        Params
        ------
        myargument : int
            Description of the argument

---MyClass2.mymethod---
This does something

        Params
        ------
        myargument : int
            Description of the argument
        argument2 : int
            Description of the additional argument

如果将装饰器作为描述符并搜索到描述符,则可以动态解析重写方法,__get__但这意味着装饰器不再可堆叠,因为它不返回实函数。

发布
问题

分享
好友

手机
浏览

扫码手机浏览