Вопрос по documentation, docstring, python, python-sphinx, restructuredtext – Существуют ли реальные альтернативы документации reStructuredText для Python? [закрыто]
Вскоре я запускаю проект 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?
вам просто нужно начать новую строку и добавить метку после каждого имени переменной. Затем он отображается в несколько строк с именами переменных, выделенных жирным шрифтом:
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
На самом деле,ReStructuredText а также руководство по стилю изPEP8 применять в основном для кодирования стандартной библиотеки Python, самой библиотеки, хотя многие сторонние программисты также согласны с этим.
Я согласен с вами, что стиль аргументов Google намного лучше с точки зрения кода. Но вы должны быть в состояниисоздать такую строку документации со сфинксом также,с сохранением новых линий и отступов, Это не выводит так хорошо, какс более сфинксовым форматированием хоть.
Во всяком случае, вы неhave to использовать сфинкс, и, кстати,autodoc модуль Сфинкса, безусловно, лишь малая его часть. Вы можете фактически использовать любой генератор документации, который способен извлекать содержимое строк документации, например,Epydoc (какая поддержкаepytext так же какreStructuredText, Javadoc или Plaintext) или жеpydoctorили даже более универсальный, какDoxygen.
Но определенно, сфинкс довольноpythonicЭто очень удобно для использования с Python и делает ваш код совместимым с экосистемой Python. я думаю, выне единственный кто думает, что это «недостаток». Возможно, они учтут эти жалобы в будущем, или, возможно, вы даже подумаете о том, чтобы изменитьautodoc Модуль сам по себе не должен быть очень сложным, это на Python, это было бы хорошим упражнением.
я используюepydoc а не сфинкс, поэтому этот ответ может не применяться.
Синтаксис reStructuredText, который вы описываете для документирования методов и функций, не является единственно возможным. Безусловно, я предпочитаю описывать параметры, используясводный список определений, что очень похоже на способ Google:
:Parameters:
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
Я бы попробовал, если бы sphix это поддерживал. Если это не так, вы также можете рассмотреть возможность использования epydoc только для этого (хотя сейчас это не так активно поддерживается).
Python делает содержимое строк документации доступным как__doc__ атрибут, прикрепленный к объекту функции / класса / переменной.
Таким образом, вы можете легко написать программу на Python, которая преобразует документацию из любого формата в любой, который вам нравится. Вы могли бы даже использовать стилизацию Javadoc, или XML, или что-то еще.
Между прочим, поскольку Sphinx написан на Python, заставить его принимать не-RST-ввод - это просто вопрос написания небольшого количества кода на Python.
Я не думаю, что есть что-то лучшее, чемsphinx для документирования проектов Python на данный момент.
Чтобы иметь более четкую строку документации, мой любимый выбор используетsphinx вместе сnumpydoc, На основании вашего примера это будет выглядеть так:
def foo(path, field_storage, temporary):
"""This is function foo
Parameters
----------
path : str
The path of the file to wrap
field_storage : :class:`FileStorage`
The :class:`FileStorage` instance to wrap
temporary : bool
Whether or not to delete the file when the File instance
is destructed
Returns
-------
describe : type
Explanation
...
Examples
--------
These are written in doctest format, and should illustrate how to
use the function.
>>> a=[1,2,3]
>>> print [x + 3 for x in a]
[4, 5, 6]
...
"""
pass
(полный примерВот), HTML output will look like этот
Я думаю, что структура первого файла более понятна и удобочитаема.руководство дает больше информации и условностей.numpydoc расширение работает сautodoc также.
Я создалРасширение сфинкса который анализирует как строки документов в стиле Google, так и в стиле NumPy, и преобразует их в стандартный reStructuredText.
Чтобы использовать его, просто установите его:
$ pip install sphinxcontrib-napoleon
И включите его в conf.py:
# conf.py
# Add autodoc and napoleon to the extensions list
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
Больше документации по НаполеонуВот.