Как сделать документацию к функции?

Как сделать документацию к функции? Как автоматически сохранить документацию в файл? Также как получить документацию из какой-либо функции?

Ответ

Документировать функции очень важно. Это помогает не только узнать что делает функция, но и подсказывает какие именованые аргументы она принимает и что в следствии может возвращать. Документировать функции очень просто. Просто и обращаться к документации каждой функции.
Чтобы создать описание функции, внутри функции перед её телом нужно сделать многострочный комментарий(делается он с помощью трёх знаков '''). Этот комментарий будет рассматриваться, как аттрибут .__doc__ и будет появляться при вызове help(), но об этом чуть позже.
Давайте сделаем небольшую функцию:
def to_str_smth(smth, step=1): smth = str(smth) return smth[::step]
Функция есть, давайте сделаем к ней описание для тех, кто будет, например, импортировать модуль с ней.
def to_str_smth(smth, step=1): """ to_str_smth(smth, step=1) Makes the input data string and return it sliced with step """ smth = str(smth) return smth[::step]
Теперь вызовем нашу документацию:
print(to_str_smth.__doc__)
Документацию можно вызвать и с помощью команды help(), но тогда свернётся весь наш аутпут и откроется что-то типа подокна (если вы знакомы с редактором nano, то вам будет проще понять), из которого можно выйти, нажав q
help(to_str_smth)
Почему не вызывем документацию у to_str_smth(), указывая скобки? Потому что так функция затребует аргументы, если они обязательны. К тому же, таким образом мы можем вернуть документацию подфункции, если она указана в return.
Посмотрим, например, на эту функцию:
def plus(a, b): """ plus(a, b) Return a + b, typed float """ return float(a + b)
Давайте попробуем вывести на экран документацию для неё, указав скобки:
print(plus().__doc__)
Как мы видим, функция запросила аргументы. Теперь давайте попробуем их передать и снова вызывать документацию:
print(plus(2.3, 2.7).__doc__)
Не совсем то, что хотелось бы видеть...
Важно соблюдать одинаковое форматирование при написании документации, как и при написании кода. Ознакомиться с рекомендациями по тому, как стоит документировать функции и классы, можно в справке PEP257. Кстати, всё, что заключённо между парой ''' игнорируется интерпретатором и таким образом можно спрятать блоки кода при его тестах.
Если мы хотим сохранить документацию, сделать это можно с помощью программы, которая идёт в комплекте с Python под названием pydoc. Для каждой версии есть свой pydoc, так что убедитесь, что вы запускаете ту версию pydoc'а, иначе может возникнуть конфликт импорта модулей.
Сделать это можно следующим образом (подразумевается, что запуск идёт из директории с модулем):
pydoc3.6 -w ./mymodule # также подойдёт pydoc -w ./mymodule.py
Таким образом будет создан html файл с вашей документацией для модуля mymodule. Дизайн не очень, зато быстро. Для стартапов пойдёт. К тому же, помимо pydoc есть множество программ, которые генерируют документацию в файл. Вот некоторые из них:
HappyDoc pudge epydoc
Обращаясь к документации с помощью help() или .__doc__, мы можем разрешить множество вопросов, связанных с импортируемыми модулями, а документируя свой код - не забыть что он делает, возвращает и для чего он нужен спустя долгое время.