[python] epydoc - оно актуально?

Вроде как сейчас Sphinx в моде… Самому интересен этот вопрос.

В смысле, вопрос о том, какой генератор документации для пайтона сейчас наиболее актуален и востребован?

классика жанра - doxygen :)

для примера http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks

## @package pyexample
#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

## Documentation for a class.
#
#  More details.
class PyClass:
   
    ## The constructor.
    def __init__(self):
        self._memVar = 0;
   
    ## Documentation for a method.
    #  @param self The object pointer.
    def PyMethod(self):
        pass
     
    ## A class variable.
    classVar = 0;

    ## @var _memVar
    #  a member variable

Для С или С++ он наверно подходит замечательно, но вот для пайтона… С первого взгляда в глаза бросается то, что он не использует строки документации. Т.е. вешь «в себе» получается. Стандартная функция help() все это нифига не увидит.

Sphinx придуман, чтобы писать всякие мануалы, когда большая часть текста пишется руками, и туда вставляется немножко документации по API, полуавтоматическим способом. А epydoc - для генерации API reference с небольшими вставками поясняющего текста. Поэтому они мирно сосуществуют, и epydoc никто не отменял. Алсо, epydoc-style докстринги - это простой ReST, и Sphinx вполне их переваривает.

да, все верно. для питона он больша за уши подтянут. просто если вся инфраструктура заточена под докси, то в приципе можно пользовать. если хочется чего-то существенного, то тут, конечно, сфинкс больше всего подходит.

Как бы даже PEP есть, в котором для докстрингов рекомендуется использовать docutils, то есть restructured text. Сходу не нашел — лень.

Ну и как стандарт де-факто это Sphinx. Где вы берете проекты с другими соглашениями, совершенно непонятно.

ReST и Sphinx. Можно и справку по API и нормальную документацию создавать.

Много пишу под Twisted, поэтому, в соответствии с их coding standard, использую epydoc-style документацию для модулей/классов/методов.

Полет нормальный.