Есть ли реальные альтернативы reStructuredText для документации Python?

Question

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

Way лучше! Но, конечно, Sphinx не будет иметь ничего из этого и отобразит весь текст после «Args:» в одной длинной строке.

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

Answer 1

Я не думаю, что есть что-то лучше, чем sphinx для документирования проектов python на данный момент.

Для получения более четкой docstring мой любимый выбор использует 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 

(полный пример Here), HTML выход будет выглядеть this

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

Answer 2

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

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

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

Answer 3

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

Я согласен с вами в том, что стиль Google для аргументов намного лучше с точки зрения кода. Но вы также должны быть в состоянии generate such docstring with sphinx, with the new lines and indentation preserved. Он не выводится так хорошо, как with a more sphinxy formatting.

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

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

Answer 4

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

Answer 5

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

Синтаксис reStructuredText, который вы описываете для документирования методов и функций, не является единственным возможным. До сих пор я предпочитаю описания параметров с помощью consolidated definition list, который очень похож на то, как 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 только для этого (хотя это не так активно поддерживается сейчас).

Answer 6

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

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 

Answer 7

Я создал Sphinx extension, который анализирует и стиль 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'] 

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