文档字符串中的重复内容答案

【问题标题】：Repetitive content in docstrings文档字符串中的重复内容
【发布时间】：2010-04-04 21:26:21
【问题描述】：

处理文档字符串中重复内容的好方法是什么？我有许多采用“标准”参数的函数，这些参数必须在文档字符串中进行解释，但最好只编写一次文档字符串的相关部分，因为这样更容易维护和更新。我天真地尝试了以下方法：

arg_a = "a: a very common argument"

def test(a):
    '''
    Arguments:
    %s
    ''' % arg_a
    pass

但这不起作用，因为当我执行help(test) 时，我看不到文档字符串。有什么好办法吗？

【问题讨论】：

听起来好像有一个更干净的抽象试图挣脱。函数有哪些，标准参数有哪些？

标签： python docstring

【解决方案1】：

正如其他答案所说，您需要更改函数对象的 __doc__ 成员。一个很好的方法是使用一个装饰器来对文档字符串执行格式化：

def fixdocstring(func):
    func.__doc__ = func.__doc__.replace('<arg_a>', 'a: a very common argument')
    #(This is just an example, other string formatting methods can be used as well.)
    return func

@fixdocstring
def test(a):
    '''
    Arguments:
    <arg_a>
    ''''
    pass

【讨论】：

+1 对于装饰器的使用，可能需要在推特上发布一些被替换的东西。这应该以某种方式清楚地表明插入了什么，并在浏览代码时寻找它。
我喜欢使用装饰器的想法。但是，如果我在新字符串中插入换行符，例如"'a: a very\ncommon argument'" 那么当我输入 help test 时，看起来好像存在缩进问题（前两行缩进了一个块太多）。知道为什么会这样吗？
@Morgoth：那是因为原始文档字符串已经包含缩进。因此，当您添加参数时，您会得到："____Arguments:\n____a very\ncommon argument"。我想您可以在 arg_a 的文档字符串中手动添加缩进，但是它不适用于缩进不同的函数。更完整（但复杂）的解决方案是让 fixdocstring 函数确定原始缩进并自动将其添加到替换字符串中。

【解决方案2】：

__doc__ 可分配给大多数用户定义的类型：

arg_a = "a: a very common argument"

def test(a):
    pass

test.__doc__ = '''
    Arguments:
    %s
    ''' % arg_a

【讨论】：

【解决方案3】：

据我所知，没有明显的方法可以做到这一点（至少没有像 Ignacio 建议的那样明确重新分配 __doc__）。

但我认为这将是一件可怕的事情。考虑一下：

如果我正在浏览您的代码并在您文件的第 300 行阅读此文档字符串，该怎么办？你真的要我去搜索论据吗？

【讨论】：

【解决方案4】：

documented docrep 井包可能就是您要找的。p>

它基于装饰器，就像interjay suggested，但智能地在您的代码中很好地记录重用文档字符串的依赖关系。这解决了issue raised by ChritopheD 问题，即真正查看您的实现的人在挖掘您的代码时必须搜索您的参数的实际定义。

【讨论】：