Мені подобається Doxygen створювати документацію коду C або PHP. У мене є майбутній проект на Python, і я думаю, що пам’ятаю, що Python не має /* .. */коментарів, а також має власний засіб самодокументування, що, здається, є пітонічним способом документування.
Оскільки я знайомий з Doxygen, як я можу використовувати його для створення своєї документації на Python? Чи є щось конкретне, про що мені слід знати?
Відповіді:
Це задокументовано на веб-сайті про кисень , але підсумовуючи тут:
Ви можете використовувати доксиген для документування вашого коду Python. Ви можете використовувати синтаксис рядка документації Python:
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
У цьому випадку коментарі будуть вилучені киснем, але ви не зможете використовувати жодну спеціальну команду доксигену .
Або ви можете (подібно до мов у стилі С під doxygen) подвоїти маркер коментаря ( #) у першому рядку перед учасником:
## @package pyexample
# Documentation for this module.
#
# More details.
## Documentation for a function.
#
# More details.
def func():
pass
У цьому випадку ви можете використовувати спеціальні команди доксигену. Немає особливого режиму виводу Python, але ви можете, мабуть, покращити результати, встановивши OPTMIZE_OUTPUT_JAVAна YES.
Чесно кажучи, я трохи здивований різницею - здається, як тільки доксиген зможе виявити коментарі в блоках ## або блоках "" ", більша частина роботи буде виконана, і ви зможете використовувати спеціальні команди в Можливо, вони очікують, що люди, які використовують "" ", дотримуються більшої практики документації Pythonic, і це заважає спеціальним командам doxygen?
Doxypy вхідний фільтр дозволяє використовувати майже всі тег форматування Doxygen в стандартному форматі Python рядки документації. Я використовую його для документування великого змішаного фреймворку ігрових програм C ++ та Python, і він працює добре.
Зрештою, у вас є лише два варіанти:
Ви генеруєте вміст за допомогою Doxygen або генеруєте вміст за допомогою програми Sphinx *.
Кисень : це не інструмент вибору для більшості проектів Python. Але якщо вам доводиться мати справу з іншими суміжними проектами, написаними на C або C ++, це може мати сенс. Для цього ви можете покращити інтеграцію між Doxygen та Python, використовуючи doxypypy .
Sphinx : інструмент дефакто для документування проекту Python. Тут у вас є три варіанти: ручний, напівавтоматичний (генерація заглушок) і повністю автоматичний (як кисень).
autosummary_generateконфігурації. Вам потрібно буде налаштувати сторінку з автозведеннями, а потім вручну відредагувати сторінки. У вас є варіанти, але мій досвід з таким підходом полягає в тому, що він вимагає занадто багато конфігурації, і зрештою, навіть після створення нових шаблонів, я виявив помилки та неможливість точно визначити, що було виставлено як загальнодоступний API, а що ні. На мою думку, цей інструмент підходить для генерації заглушок, що вимагатиме ручного редагування, і не більше того. Це як ярлик, щоб закінчити вручну.Є й інші варіанти, на які слід звернути увагу:
__all__змінну explicite.
Sphinx - це, головним чином, інструмент для форматування документів, написаних незалежно від вихідного коду, наскільки я розумію.
Для генерації документів API із рядків докторів Python провідними інструментами є pdoc та pydoctor . Ось згенеровані pydoctor документи для API для Twisted і Bazaar .
Звичайно, якщо ви просто хочете поглянути на рядки документації під час роботи над матеріалом, існує інструмент командного рядка " pydoc ", а також help()функція, доступна в інтерактивному інтерпретаторі.
Іншим дуже хорошим інструментом документації є сфінкс . Він буде використаний для майбутньої документації python 2.6 і використовується django та багатьма іншими проектами python.
З веб-сайту сфінкса: