RU | EN

Документируй это

У Python есть одна замечательная особенность - у него есть встроенные средства документирования кода. Так называемые docstring’и. О них и пойдет речь…

Docstring - (сокращение от documentation string, строка документации) встроенное средство документирования модулей, функций, классов и методов. Делается очень просто - сразу после определения указывается строковое значение, которое и будет docstring’ом. 

>>> def test():
...    "This is the test's docstring"
...    print "opa"
Получить доступ к docstring можно так: 
>>> test.__doc__
"This is the test's docstring"
Либо так: 
>>> help(test)
Help on function test in module __main__:

test()
    This is the test's docstring
Существуют инструменты, которые позволяют извлекать docstring не по одиночке, а для целого модуля/пакета. О них и пойдет речь.

pydoc

Pydoc входит в стандартную поставку Python. Для того, чтобы сгенерировать HTML-документацию для модуля, достаточно выполнить: 
pydoc -w module_name
и Вы на выходе получите module_name.html. Одна интересная возможность pydoc - использование его как http-сервера для документации по всем установленным модулям. Достаточно запустить pydoc с параметром -g: 
pydoc -g
PyDoc показывает docstring как есть, он не использует какие-либо правила форматирования.

HappyDoc

HappyDoc - достаточно популярный инструмент (используется в достаточно крупных проектах, например NumPy), хотя прекратил свое развитие где-то три года назад. В отличии от pydoc, использующего интроспекцию (т.е. импортирует модуль и "обходит" все объекты) для создания документации, HappyDoc самостоятельно разбирает Python-исходники и уже по результатам разбора составляет документацию. Такой подход имеет как свои плюсы, так и минусы. Положительные стороны: * можно обрабатывать модули, у которых не удовлетворены зависимости, либо не желательно их импортировать * есть возможно обрабатывать комментарии, которые при интроспекции "теряются"
Отрицательные: * нет возможности обрабатывать C-модули * сложности в обработки модуля, "хитрым" образом меняющего пространство имен, или, например, генерирующегося "на лету"
HappyDoc достаточно гибок - поддерживает различные типы разметок (StructuredText, StructuredTextNG, plain text, raw text), можно создать свой собственный.

pudge

Pudge - в отличии от остальных упомянутых инструментов, ориентирован, в первую очередь, для публикации API-документации в интернете. Также возможна интеграция с Trac. Внешний вид готовой документации задается шаблонами kid. Для построения документации использует как разбор кода собственным парсером, так и интроспекцию. Внутри docstring’ов позволяет форматировать текст по правилам reStructuredText. Одна из особенностей pudge - помимо представления информации из docsting’ов, он сохраняет в html весь код модуля.
Из недостатков могу отметить "неровности" в процессе установки - кое-где приходится "напильником" дорабатывать. Однако автор сразу предупреждает о том, что pudge находится в процессе активной доработки.

epydoc

Epydoc - на мой взгляд, наиболее интересный инструмент для создания API-документации. Я рассмотрю версию 3.0, которая обладает более широкими возможностями, чем предыдущая 2.1.
Умеет сохранять "расцвеченный" код модуля, для построения документации использует и интроспекцию, и разбор кода. В этом плане он схож с pudge. Шаблоны он не использует, лишь при помощи css можно менять цветовую схему. Помимо html умеет выводить в LaTeX и pdf. Из отличительных особенностей отмечу использование собственной разметки epytext, хотя поддерживаются reStructuredText и JavaDoc. Далее, при помощи graphviz умеет строить UML-диаграммы классов.
В целом, мне он понравился больше всех. В скором времени расскажу об epydoc чуть подробнее.

Примеры

Для примера написал ничего-не-делающий модуль foo: 
"""Module's docstring"""

__docformat__ = "restructuredtext"

CONST='Opa-la' #: doccomment for CONST

def bar(x):
    """bar - returns repr(x)"""

    return repr(x)

class Foo(object):
    """Example of class'es doctstring"""

    classattr = "Class attribute" #: doccomment for class attribute

    def __init__(self, arg):
        """
        Constructor for foo object

        :param arg: Dummy argument for constructor
        :type arg: basestring
        """
        self.arg = arg

    def go(self, parm):
        """

        Dummy action for object Foo

        :param parm: Dummy parameter of method

        :return: Returns parm
        """
        x = repr(parm) #: doccomment for x: x is a representation of parm
        return parm
И обработал его каждым из упомянутых инструментов. Результат можете взять здесь

Источники:
gorod-omsk.ru/blog/pythy

alafin Комментарии: 0 09.09.2006

Комментарии: