Вскоре я начинаю проект 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?