Сфинкс, лучшие практики

Я только начал использовать инструмент Sphinx для создания документации для моего кода. Но я немного смущен, потому что это не так просто, как я ожидал. Я создаю документ Sphinx, используя:

sphinx-quickstart

а затем создаю файлы *.rst в папку "source". Похоже, мне нужно создать *.rst файл для каждого модуля, для которого я хочу создать документ. Для test.py я создаю test.rst. Внутри test.rst у меня есть:

.. automodule:: test
    :members:
    :show-inheritance:

Затем внутри test.py у меня есть:

"""
.. module:: test
   :platform: Unix, Windows
   :synopsis: A useful module indeed.
"""

Затем я создаю документацию, используя:

sphinx-build -b html source/ build/

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

Спасибо.

Ответ 1

Нет более простого способа. Sphinx не является генератором документов API, подобным epydoc, но вместо этого фокусируется на рукописной документации. Следовательно, вам нужно написать много документов вручную.

Преимущество состоит в том, что вы также можете писать документацию за пределами документации API (например, учебники, руководства по использованию, даже документацию для конечных пользователей) и что вы можете структурировать документацию API логически, помимо простого простого алфавитного списка доступных объектов. Такая документация, как правило, намного легче понять и намного проще в использовании, если все сделано правильно.

Взгляните на документацию по хорошо известным проектам (например, Werkzeug или Sphinx), чтобы увидеть некоторые рекомендации.

Ответ 2

Один простой способ быстро документировать ваше приложение - просто написать docstrings в классы и методы в соответствии с обычным, а затем дополнить их, если это необходимо в файлах .rst.

template.rst:

Templating
----------
Notes about templating would go here.

.. automodule:: myapp.lib.template
    :members:
    :undoc-members:

    .. py:attribute:: filepath

        Full path to template file. This attribute is added in runtime, so
        it has to be documented manually.

MyApp/Library/template.py:

class Template(object):
    '''
    Class for rendering templates.

    Usage example::

        >>> t = Template('somefile')
        >>> document = t.render(variables={'ID': 1234})

    Rendered document is always returned as a unicode string.
    '''

    def render(self, **args):
        '''
        Render template. Keyword arguments are passed `as-is` to renderer.
        '''

Ответ 3

Вы можете использовать sphinx-apidoc для создания файлов rst для вас.

sphinx-apidoc -o outputdir pythondir

Пример выполнения вывода:

% sphinx-apidoc -o source/ ../
File source/module1.rst already exists, skipping.
File source/module2.rst already exists, skipping.
Creating file source/module3.rst.

rst docs updated in source/.

sphinx-apidoc не будет изменять существующие файлы, вы можете принудительно перезаписать флаг -f.