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: 

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

One Solution collect form web for “Python-Sphinx: как документировать один файл с функциями?”

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

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

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

 .. toctree:: :maxdepth: 4 modules 

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

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

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

[РЕДАКТИРОВАТЬ]

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

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

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

     .. toctree:: :maxdepth: 2 modules 
  7. Выполнить sphinx-apidoc -o . .. sphinx-apidoc -o . ..
  8. Сгенерируйте вывод html: make html
  9. Просмотрите свою документацию: firefox _build/html/index.html
  • Пусть sphinx использует версию из setup.py
  • как сгенерировать сигнатуру функции с помощью sphinx?
  • Как настроить Sphinx для условного исключения некоторых страниц?
  • Перенос с Javadoc на Python Documentation
  • Каков правильный способ документировать параметр ** kwargs?
  • Как я могу поместить ссылку interphinx на произвольный метод в документации стандартной библиотеки?
  • Объявление функции переопределения в autodoc для sphinx
  • Получить «плоский» элемент для автомодуля sphinx
  • Python - лучший язык программирования в мире.