Создание документации для нескольких папок с помощью Sphinx

В настоящее время я работаю над проектом Python, который становится больше, чем ожидалось.
Мой код полностью задокументирован с помощью строк документации, и теперь я хотел бы создать исчерпывающую документацию с помощью Sphinx.
Однако, что бы я ни пытался, я не могу найти способ сгенерировать все в одной команде.

Вот обновленная структура моего проекта:

.
├── docs
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
├── project
│   ├── module1
│   │   ├── file1.py
│   │   └── file2.py
│   ├── ext_files
│   │   └── >files we dont care about
│   ├── module2
│   │   ├── file3.py
│   │   ├── file4.py
│   │   └── file5.py
│   ├── module3
│   │   ├── file6.py
│   │   ├── file7.py
│   │   ├── file8.py
│   │   └── file9.py
│   └── main.py
├── README.md
└── requirements.txt

В идеале я бы хотел, чтобы HTML-документация следовала этой структуре.

Что я пробовал:

  • sphinx-quickstart, давая правильную информацию
  • Затем отредактируйте файл conf.py, добавив sphinx.ext.autodoc, sphinx.ext.napoleon, а также sys.path.abspath(..) (сокращенно)
  • Использование sphinx-apidoc в моих 3 разных папках разными способами
  • Перемещение файлов .rst в подкаталогах в моем основном каталоге документов
  • Изменение index.rst и/или modules.rst и добавление к ним имен моих папок/файлов

Я также пробовал вручную добавлять директивы automodule, а также создавать подмодули.
Я попытался настроить sphinx-autogen для автоматического обнаружения разных модулей.
Однако, что бы я ни делал, он либо только генерирует документацию для моего файла main.py, либо вообще ничего.

Пожалуйста, помогите мне, так как я схожу с ума. Независимо от того, какому учебнику я следую или какую документацию я читаю, я не могу найти ответ.
Заранее спасибо!

Проекты sphinx и Python обычно структурированы с общим именем пакета (например, myhandlers), и при необходимости под ним создаются подпакеты (например: myhandlers.misc_handlers, .data_handlers и т. д.). Показанная выше структура отличается от стандартной, поэтому заставить ее работать может быть сложнее, чем обычно. Является ли это устаревшей кодовой базой, рефакторинг которой затруднен?

Alexander L. Hayes 13.12.2022 17:23

Вы можете изучить соглашения из существующих проектов, таких как github.com/lextudio/pysnmp и pysnmp.com/pysnmp

Lex Li 13.12.2022 18:34

Здравствуйте, спасибо за ваши комментарии. Я обновил свою структуру (отражено в исходном посте). Однако мне все еще не удается создать полную документацию для всех модулей. Я изменил свой системный путь на «../project» в conf.py и использовал sphinx-apidoc. main.py по-прежнему единственный файл со сгенерированной документацией! Заранее спасибо за помощь.

Koreos 14.12.2022 08:57
Почему в Python есть оператор "pass"?
Почему в Python есть оператор "pass"?
Оператор pass в Python - это простая концепция, которую могут быстро освоить даже новички без опыта программирования.
Некоторые методы, о которых вы не знали, что они существуют в Python
Некоторые методы, о которых вы не знали, что они существуют в Python
Python - самый известный и самый простой в изучении язык в наши дни. Имея широкий спектр применения в области машинного обучения, Data Science,...
Основы Python Часть I
Основы Python Часть I
Вы когда-нибудь задумывались, почему в программах на Python вы видите приведенный ниже код?
LeetCode - 1579. Удаление максимального числа ребер для сохранения полной проходимости графа
LeetCode - 1579. Удаление максимального числа ребер для сохранения полной проходимости графа
Алиса и Боб имеют неориентированный граф из n узлов и трех типов ребер:
Оптимизация кода с помощью тернарного оператора Python
Оптимизация кода с помощью тернарного оператора Python
И последнее, что мы хотели бы показать вам, прежде чем двигаться дальше, это
Советы по эффективной веб-разработке с помощью Python
Советы по эффективной веб-разработке с помощью Python
Как веб-разработчик, Python может стать мощным инструментом для создания эффективных и масштабируемых веб-приложений.
0
3
75
1
Перейти к ответу Данный вопрос помечен как решенный

Ответы 1

Ответ принят как подходящий

Попробовав почти все, я решил это:

  1. Обновление структуры моего проекта, чтобы отразить приведенную выше (вдохновленную ссылкой, данной Лексом Ли)
  2. Удалил все мои файлы sphinx, перезапустил sphinx-quickstart, обязательно разделил сборку и исходный код
  3. Убедитесь, что в каждой подпапке project есть файл __init__.py
  4. Из папки docs/source отредактировал мой conf.py файл и добавил
import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', 'project'))
sys.path.insert(0, basedir)
  1. Добавлены sphinx.ext.autodoc и sphinx.ext.napoleon в расширения
  2. Добавлено modules в соответствии с директивой toctree в index.rst
  3. Побежал sphinx-apidoc -o ./source ../project -f
  4. Потом из docs/ побежал make html.

После запуска sphinx-apidoc убедитесь, что файл <module>.rst создан для каждого модуля, который у вас есть или который нужно задокументировать.

Я чувствую, что этот подробный ответ может быть кому-то полезен, так как он представляет собой компиляцию нескольких ответов StackOverflow.

Другие вопросы по теме