Как настроить автоматическую генерацию документации?

Question

[Utter_step]

Собственно, вопрос:
Я пишу сейчас небольшой проект (на Python'e), стараюсь все функции и методы документировать подобным образом:

"""
Generates random secret. Inputs and return are similar to share()'s, except "secret", which is not
in use here.

@param passphrase:  password, if you wish to keep your secret totally confidential
@param recipient:   recipient's e-mail, if you wish to send him an invitation to see your secret
@param ttl:         TTL of your secret, in seconds. Set to one day by default

@type passphrase:   string
@type recipient:    string
@type ttl:          int

@return res:        dict
"""

Чем лучше всего воспользоваться для создания хотябы каркаса документации?

Comments

[Utter_step]

Забавный эффект. @что-то воспринимается как ник хабраюзера даже в теге <sourcе>.

[Utter_step]

изначально в коде было
@param…
@typе…
@rеturn…

Answer 1

[klen]

Для питона стандартом де-факто является: Sphinx (http://sphinx.pocoo.org/contents.html)

Answer 2

[Maxim Avanov]

До Sphinx, вплоть до релиза Python 2.5, разработчики пользовались генератором epydoc и, често признаться, некоторых его свойств сильно не хватает в Sphinx. Например, автоматическая (т.е. совсем, т.е. без дополнительной разметки) документация API библиотек, а также построение графов зависимостей между объектами. Ну и чисто субъективно, оформление и навигация в старой документации мне казалась чище и проще.

Попробуйте, возможно вам понравится.