Вопрос по documentation, docstring, python, python-sphinx, restructuredtext – Существуют ли реальные альтернативы документации reStructuredText для Python? [закрыто]

50

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

Путь Google тоже использует rst. Это намного понятнее Davoud Taghawi-Nejad

Ваш Ответ

7   ответов
0

вам просто нужно начать новую строку и добавить метку после каждого имени переменной. Затем он отображается в несколько строк с именами переменных, выделенных жирным шрифтом:

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
7

На самом деле,ReStructuredText а также руководство по стилю изPEP8 применять в основном для кодирования стандартной библиотеки Python, самой библиотеки, хотя многие сторонние программисты также согласны с этим.

Я согласен с вами, что стиль аргументов Google намного лучше с точки зрения кода. Но вы должны быть в состояниисоздать такую строку документации со сфинксом также,с сохранением новых линий и отступов, Это не выводит так хорошо, какс более сфинксовым форматированием хоть.

Во всяком случае, вы неhave to использовать сфинкс, и, кстати,autodoc модуль Сфинкса, безусловно, лишь малая его часть. Вы можете фактически использовать любой генератор документации, который способен извлекать содержимое строк документации, например,Epydoc (какая поддержкаepytext так же какreStructuredText, Javadoc или Plaintext) или жеpydoctorили даже более универсальный, какDoxygen.

Но определенно, сфинкс довольноpythonicЭто очень удобно для использования с Python и делает ваш код совместимым с экосистемой Python. я думаю, выне единственный кто думает, что это «недостаток». Возможно, они учтут эти жалобы в будущем, или, возможно, вы даже подумаете о том, чтобы изменитьautodoc Модуль сам по себе не должен быть очень сложным, это на Python, это было бы хорошим упражнением.

10

я использую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 только для этого (хотя сейчас это не так активно поддерживается).

Sphinx поддерживает это, я пишу свои строки документации таким образом, и они отображаются нормально (не уверен, что вывод такой же, как для обозначения, которое показывает OP, но он более чем читабелен как в источнике, так и в визуализированных документах).
3

Python делает содержимое строк документации доступным как__doc__ атрибут, прикрепленный к объекту функции / класса / переменной.

Таким образом, вы можете легко написать программу на Python, которая преобразует документацию из любого формата в любой, который вам нравится. Вы могли бы даже использовать стилизацию Javadoc, или XML, или что-то еще.

Между прочим, поскольку Sphinx написан на Python, заставить его принимать не-RST-ввод - это просто вопрос написания небольшого количества кода на Python.

31

Я не думаю, что есть что-то лучшее, чем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 также.

Не должен & lt; t & quot; array_like & quot; быть "повторяемым"? Также спасибо за ссылки :-) Hubro
Фантастика! Это обеспечивает идеальное промежуточное звено для ясного, но бессильного стиля Google и запутанного и мощного стиля отдыха Сфинкса (например: param derp: derp.)
Хммм выглядит хорошо, кажется, что привносит в sphinx стиль, похожий на google, нужно попробовать +1.
Моя единственная жалоба на numpydocs заключается в том, что у вас в итоге есть 2 ссылки на модули, одна для py-модулей, а другая для np-модулей.
@ шутки, так что, может быть, вы могли бы выразить свой голос;
67

Я создалРасширение сфинкса который анализирует как строки документов в стиле 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']

Больше документации по НаполеонуВот.

Наполеон лучше, чем Numpydoc, и начиная с версии 1.3.1 он поставляется в Sphinx, аsphinx.ext.napoleon, Это на самом деле лучший ответ.
4

Выcan пишите строки документов в любом формате, который вам нравится. Однако ради любого другого программиста на Python лучше всего использовать разметку и инструменты, которые они уже знают. Их жизнь проще, если вы придерживаетесь ReST и Sphinx.

Похожие вопросы