Я не рекомендую пытаться делать что-то сложное с последовательностями документов.Лучше сохранять простоту строк документации и делать что-то еще, если вы хотите сделать доступными несколько различных вариантов документации.
Если вы действительно хотите сделать то, что вы описали, я предлагаю вам использовать теги для разделения разделов внутри строк документации,Вот так:
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
Тогда вы можете довольно легко разбить вашу строку на куски, и когда пользователь выбирает пункт меню, показывать только соответствующие куски.
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, вы можете сказать «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 () в декоратор, но сейчас у меня нет времени.