Сфинкс, лучшие практики - PullRequest
Новая
       0

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

14 голосов
/ 24 мая 2011

Я только начал использовать инструмент 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 файла для каждого модуля.

Спасибо.

Ответы [ 3 ]

11 голосов
/ 24 мая 2011

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

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

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

10 голосов
/ 24 мая 2011

Один простой способ быстро документировать ваше приложение - просто записать строки документации в классы и методы, как обычно, а затем дополнить их, если требуется, в файлах .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 / Библиотека / 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 голосов
/ 26 сентября 2014

Вы можете использовать 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.

...