python - 单个模块/函数等的文档字符串超过 1 个？

Question

我正在使用 python 3.1。

是否可以为单个模块或函数创建超过 1 个文档字符串？我正在创建一个程序，我打算有多个文档字符串，每个文档字符串都有一个类别。我打算将程序提供给其他人，以便他们可以使用它，并且为了让程序员和非程序员都可以轻松使用，我在程序本身中放置了对文档字符串的引用。

更具体地说，我在程序/模块中有一个菜单作为界面，其中一个选项将允许访问模块文档字符串以获取程序文档。因此，如果可能的话，我想制作多个文档字符串来对不同类型的文档进行分类。因此，如果用户想要查看文档的某些部分，他们会更容易。

例如。第一个文档字符串包含有关如何使用该程序的说明。第二个文档字符串包含有关程序的一部分如何工作的信息。第三个文档字符串包含有关另一部分如何工作的信息。等

这可能吗？如果是这样，您如何引用它们？

更新:添加了评论。

我最初的想法是在以下意义上实际上拥有多个文档字符串:

def foo():
    """docstring1: blah blah blah"""
    """docstring2: blah blah blah"""
    pass # Insert code here

然后我可以使用一些代码来引用这些文档字符串中的每一个。那么，我猜这不可能吧？

Answer 1

我不建议尝试使用文档字符串做一些复杂的事情。最好保持文档字符串简单，如果您想提供一堆不同的文档选项，请做其他事情。

如果你真的想做你描述的事情，我建议你使用标签来分隔文档字符串中的部分。像这样:

def foo(bar, baz):
    """Function foo()

* Summary:
    Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them.

* Developers:
    When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests.

* Testers:
    When you test foo, be sure to try negative values for baz.
"""
    pass # code would go here

然后您可以非常轻松地将字符串分成 block ，当用户选择菜单项时，只显示适当的 block 。

s = foo.__doc__  # s now refers to the docstring

lst = s.split("\n* ")
section = [section for section in lst if section.startswith("Developers")][0]
print(section) # prints the "Developers" section

这样，当您在交互式 Python shell 中工作时，您可以说“help(foo)”，您将看到所有文档字符串。而且，您并没有改变 Python 基本部分的基本行为，这会吓到其他试图研究您的代码的人。

您还可以做一些更简单的事情:只需为不同的目的制作一个大型的全局文档字符串字典，并从源代码中为每个新事物更新它。

doc_developers = {}doc_testers = {}

def foo(bar, baz):
    """Function foo()

Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them."
    pass # code goes here

doc_developers["foo"] = "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests."

doc_testers["foo"] = "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests."

我最不喜欢的一点是，如果您更改函数 foo 的名称，您将需要在多个地方更改它:一次在实际的 def 中，一次在每个字典更新行。但是您主要可以通过编写一个函数来解决这个问题:

def doc_dict = {} # this will be a dict of dicts
doc_dict["developers"] = {}
doc_dict["testers"] = {}

def doc_update(fn, d):
    name = fn.__name__
    for key, value in d.items():
        doc_dict[key][name] = value

def foo(bar, baz):
    """Function foo()

Function foo() handles all your foo-ish needs.  You pass in a bar and a baz and it foos them."
    pass # code goes here

d = { "developers": "When you change foo(), be sure you don't add any global variables, and don't forget to run the unit tests.",
"testers": " When you test foo, be sure to try negative values for baz."}

doc_update(foo, d)

可能有一种方法可以将 doc_update() 变成装饰器，但我现在没时间了。