Python-Sphinx: как документировать один файл с функциями?

У меня есть файл Python с функциями (lib.py), без классов. Каждая функция имеет следующий стиль:

def fnc1(a,b,c):
    '''
    This fonction does something.

    :param a: lalala
    :type a: str
    :param b: hahaha
    :type b: int
    :param c: hohoho
    :type c: int

    :rtype: int

    '''

    print a
    d = b + c

    return d

Я просто хочу документировать каждую функцию (входы и выходы) с помощью Sphinx.

После выполнения sphinx-quickstart я определил путь в conf.py с моим lib.py. Но выходной HTML-файл (страница приветствия) пуст.

Если я напишу себя в index.rst :

.. function:: func1(a,b,c)
    This fonction does something.

    :param a: lalala
    :type a: str
    :param b: hahaha
    :type b: int
    :param c: hohoho
    :type c: int
    :rtype: int

все в порядке, он показывает входы и выходы в HTML-файл. Но как это сделать автоматически?

Обычно, я думаю, он должен делать это в lib.rst после выполнения sphinx-apidoc -o , но в lib.rst есть только:

lib module
==================

.. automodule:: lib
    :members:
    :undoc-members:
    :show-inheritance:

Может кто-нибудь объяснить мне шаг за шагом, что именно я должен делать?

10 голосов | спросил natalia 3 TueEurope/Moscow2013-12-03T19:12:07+04:00Europe/Moscow12bEurope/MoscowTue, 03 Dec 2013 19:12:07 +0400 2013, 19:12:07

1 ответ


0

Во-первых, при запуске sphinx-quickstart убедитесь, что вы выбрали autodoc :

autodoc: automatically insert docstrings from modules (y/N) [n]: y

Затем в сгенерированном index.rst я обычно добавляю modules для автоматического включения всех модулей (следите за идентификацией).

.. toctree::
   :maxdepth: 4

   modules

После этого sphinx-apidoc -o создает для меня документацию.

Я написал руководство по использованию Sphinx для кода Python, используемого во встроенных системах, но первые шаги Руководства также могут быть вам полезны:

Как создать документацию sphinx для кода Python, выполняемого во встроенной системе

[EDIT]

Вот пошаговый список:

  1. Создать lib.py
  2. Создать папку с документацией: mkdir doc

    ├── doc/
    └── lib.py
    
  3. Введите документ /: cd doc
  4. Выполните sphinx-quickstart (обязательно выберите autodoc: y, Makefile: y)
  5. Измените conf.py , указав sys.path: sys.path.insert(0, os.path.abspath('..'))
  6. Отредактируйте index.rst и укажите modules в toctree:

    .. toctree::
        :maxdepth: 2
    
        modules
    
  7. Выполнить sphinx-apidoc -o . ..
  8. Создать вывод html: make html
  9. Просмотрите документацию: firefox _build/html/index.html
ответил jcarballo 3 TueEurope/Moscow2013-12-03T19:36:17+04:00Europe/Moscow12bEurope/MoscowTue, 03 Dec 2013 19:36:17 +0400 2013, 19:36:17

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

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132