Я пытаюсь автоматически сгенерировать базовую документацию для своей кодовой базы с помощью Sphinx. Однако у меня возникли трудности с указанием Sphinx рекурсивно сканировать мои файлы.
У меня есть кодовая база Python со структурой папок, например:
<workspace>
└── src
└── mypackage
├── __init__.py
│
├── subpackageA
│ ├── __init__.py
│ ├── submoduleA1
│ └── submoduleA2
│
└── subpackageB
├── __init__.py
├── submoduleB1
└── submoduleB2
Я запустил sphinx-quickstart в <workspace>, так что теперь моя структура выглядит так:
<workspace>
├── src
│ └── mypackage
│ ├── __init__.py
│ │
│ ├── subpackageA
│ │ ├── __init__.py
│ │ ├── submoduleA1
│ │ └── submoduleA2
│ │
│ └── subpackageB
│ ├── __init__.py
│ ├── submoduleB1
│ └── ubmoduleB2
│
├── index.rst
├── _build
├── _static
└── _templates
Я прочитал краткое руководство, и хотя я m все еще пытается понять документацию, меня беспокоит то, как он сформулирован, что Sphinx предполагает, что я собираюсь вручную создавать файлы документации для каждого отдельного модуля / класса / функции в моей кодовой базе.
Тем не менее, я заметил оператор automdule и включил autodoc во время быстрого запуска, поэтому я надеюсь, что большая часть документации может быть сгенерирована автоматически. Я изменил свой conf.py, чтобы добавить мою папку src в sys.path, а затем изменил свой index.rst, чтобы использовать automdule. Итак, теперь мой index.rst выглядит так:
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. automodule:: alphabuyer
:members:
У меня есть десятки классов и функций, определенных в подпакетах. Но когда я бегу:
sphinx-build -b html . ./_build
он сообщает:
updating environment: 1 added, 0 changed, 0 removed
И, похоже, это не помогло импортировать что-либо в мой пакет. Просмотр сгенерированного index.html ничего не показывает рядом с Contents :. На странице указателя отображается только mypackage (модуль), но щелчок по нему показывает, что он также не имеет содержимого.
Как вы заставляете Sphinx рекурсивно анализировать пакет и автоматически генерировать документацию для каждого класса / метода / функции, с которыми он сталкивается, без необходимости вручную перечислять каждый класс самостоятельно?
