Минимальный рабочий пример для документации пакета с использованием Sphinx в Python

Я пытаюсь документировать пакет в python. На данный момент у меня есть следующая структура каталогов:

. └── project ├── _build │  ├── doctrees │  └── html │  ├── _sources │  └── _static ├── conf.py ├── index.rst ├── __init__.py ├── make.bat ├── Makefile ├── mod1 │  ├── foo.py │  └── __init__.py ├── mod2 │  ├── bar.py │  └── __init__.py ├── _static └── _templates 

Это дерево является результатом обстрела sphinx-quickstart . В conf.py я sys.path.insert(0, os.path.abspath('.')) И у меня есть extensions = ['sphinx.ext.autodoc'] .

Мой index.rst :

 .. FooBar documentation master file, created by sphinx-quickstart on Thu Aug 28 14:22:57 2014. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to FooBar's documentation! ================================== Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 

Во всех __init__.py меня есть docstring, и то же самое касается модулей foo.py и bar.py Однако при запуске make html в проекте я не вижу ни одного из документов … Я был бы рад опубликовать дополнительную информацию по мере необходимости.

Я пытаюсь придумать минимальный рабочий пример автоматической документации проекта python.

One Solution collect form web for “Минимальный рабочий пример для документации пакета с использованием Sphinx в Python”

Вот схема:

  1. Документируйте свой пакет, используя docstrings в источниках.
  2. Используйте sphinx-quickstart для создания проекта Sphinx.
  3. Запустите sphinx-apidoc для создания источников .rst, настроенных для использования с autodoc . Использование этой команды с флагом -F также создает полный проект Sphinx. Если ваш API сильно изменится, вам может понадобиться повторно запустить эту команду несколько раз.
  4. Создайте документацию, используя sphinx-build .

Заметки:

  • Sphinx требует файлов .rst с такими директивами, как autoclass или autoclass , чтобы генерировать документацию по API. Он не автоматически извлекает что-либо из источников Python без этих файлов. Это отличается от того, как работают такие инструменты, как Epydoc или Doxygen. Различия здесь развиты немного подробнее: Какова взаимосвязь между докутиками и Сфинксом? ,

  • После запуска sphinx-apidoc может потребоваться настроить sys.path в conf.py для autodoc, чтобы найти ваши модули.

  • Чтобы избежать странных ошибок, подобных этим вопросам, как мне разрешить конфликт OptionParser и sphinx-build в большом проекте? , Является ли OptionParser конфликтом со сфинксом? , убедитесь, что код правильно структурирован, используя if __name__ == "__main__": защищает при необходимости.

  • Как я могу создать документацию для средства определения свойств Python с помощью Sphinx?
  • Как включить локальную оглавление в документ Sphinx?
  • Документирование записи сценария python (__name__ == '__main__') с использованием sphinx
  • Использование sphinx для автоматической документирования класса python, модуля
  • как показать атрибуты экземпляра в документе sphinx?
  • Настроить тему sphinxdoc
  • Sphinx и argparse - скрипты командной строки autodocumenting?
  • Выполнить код в autodoc docstring
  • Как ссылаться на документированный параметр функции Python с помощью разметки Sphinx?
  • Каков наилучший способ включить PDF в мою документацию по Sphinx?
  • Как расширить все подразделы на боковой панели в Сфинксе
  • Python - лучший язык программирования в мире.