Существуют ли реальные альтернативы документации reStructuredText для Python? [закрыто]

Вскоре я начинаю проект Python с открытым исходным кодом и пытаюсь заранее решить, как писать свои строки документации.Очевидным ответом было бы использование reStructuredText и Sphinx с autodoc, потому что мне действительнонравится идея просто правильно документировать мой код в строках документации, а Sphinx автоматически создает для меня документ API.

Проблема заключается в используемом синтаксисе reStructuredText — я думаю, что он совершенно нечитаем до того, как будет отрендерен. Например:

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File instance
    is destructed
:type temporary: bool

Вы должны действительнозамедлиться и потратить минуту, чтобы разобраться в этой синтаксической мешанине. Мне гораздо больше нравится способ Google ( Руководство по стилю Google Python), аналог которого выглядит следующим образом:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The FileStorage instance to wrap
    temporary (bool): Whether or not to delete the file when the File
        instance is destructed

Намноголучше! Но, конечно, Sphinx не будет иметь ничего из этого и отобразит весь текст после «Args:» в одну длинную строку.

Итак, подведем итог: прежде чем я отправлюсь и оскверню свою кодовую базу этим синтаксисом reStructuredText, я хотел бы знать, есть ли какие-либо реальные альтернативы использованию его и Sphinx, за исключением простого написания моей собственной документации по API. Например, есть ли расширение для Sphinx, которое обрабатывает стиль строки документации Google Style Guide?

53
задан bmu 24 June 2012 в 04:37
поделиться