В настоящее время я работаю над проектом 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, либо вообще ничего.
Пожалуйста, помогите мне, так как я схожу с ума. Независимо от того, какому учебнику я следую или какую документацию я читаю, я не могу найти ответ.
Заранее спасибо!
Вы можете изучить соглашения из существующих проектов, таких как github.com/lextudio/pysnmp и pysnmp.com/pysnmp
Здравствуйте, спасибо за ваши комментарии. Я обновил свою структуру (отражено в исходном посте). Однако мне все еще не удается создать полную документацию для всех модулей. Я изменил свой системный путь на «../project» в conf.py и использовал sphinx-apidoc. main.py по-прежнему единственный файл со сгенерированной документацией! Заранее спасибо за помощь.
Попробовав почти все, я решил это:
sphinx-quickstart
, обязательно разделил сборку и исходный кодproject
есть файл __init__.py
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)
sphinx.ext.autodoc
и sphinx.ext.napoleon
в расширенияmodules
в соответствии с директивой toctree в index.rst
sphinx-apidoc -o ./source ../project -f
docs/
побежал make html
.После запуска sphinx-apidoc
убедитесь, что файл <module>.rst
создан для каждого модуля, который у вас есть или который нужно задокументировать.
Я чувствую, что этот подробный ответ может быть кому-то полезен, так как он представляет собой компиляцию нескольких ответов StackOverflow.
Проекты sphinx и Python обычно структурированы с общим именем пакета (например,
myhandlers
), и при необходимости под ним создаются подпакеты (например:myhandlers.misc_handlers
,.data_handlers
и т. д.). Показанная выше структура отличается от стандартной, поэтому заставить ее работать может быть сложнее, чем обычно. Является ли это устаревшей кодовой базой, рефакторинг которой затруднен?