我有一些彼此继承的类。所有类都包含相同的方法(我们称它为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)
[...]
可能不太理想,但是也许您可以使用装饰器来扩展文档字符串。例如:
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__
但这意味着装饰器不再可堆叠,因为它不返回实函数。