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

Ответ 1

Я не думаю, что есть что-то лучше, чем 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 будет выглядеть как this

Я думаю, что структура первого файла более понятна и понятна. В руководстве приведены дополнительные сведения и условные обозначения. Расширение numpydoc также работает с autodoc.

Ответ 2

Я создал расширение Sphinx, которое анализирует как docstrings стиля стиля 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']

Дополнительная документация по napoleon здесь.

Ответ 3

Я использую epydoc, а не sphinx, поэтому этот ответ может не применяться.

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

Ответ 4

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

Я согласен с вами в том, что стиль Google для аргументов намного лучше с точки зрения кода. Но вы должны генерировать такую ​​docstring вместе с sphinx, с помощью новые линии и отступы сохраняются. Он не выводится так хорошо, как с более форматированием sphinxy.

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

Но определенно, sphinx довольно питонов, очень удобен для использования с Python и делает ваш код совместимым с экосистемой Python. Я думаю, что вы не единственный, кто думает, что это "недостаток" . Возможно, они будут учитывать эти жалобы в будущем, или, может быть, вы даже можете подумать о модуляции модуля autodoc самостоятельно, не должно быть очень сложно, это в Python, это было бы хорошим упражнением.

Ответ 5

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

Ответ 6

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

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

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

Ответ 7

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

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