Вскоре я запускаю проект Python с открытым исходным кодом и пытаюсь заранее решить, как писать строки документации. Очевидным ответом будет использование reStructuredText и Sphinx с autodoc, потому что яreally как идея простого правильного документирования моего кода в моих строках документов, тогда 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

Ты долженreally замедлиться и занять минуту, чтобы разобраться в этом синтаксическом беспорядке. Мне больше нравится способ 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

Way лучше! Но, конечно же, у Sphinx ничего этого не будет, и он отображает весь текст после & quot; Args: & quot; в одну длинную очередь.

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