py-export-api-docs

Экспорт Markdown-документации API для пакетов из requirements.txt.

Скрипт создаёт временное виртуальное окружение (не трогает системный Python), устанавливает зависимости и генерирует документацию через pydoc-markdown 4.x.

Требования

• Python 3 с модулем venv (на Debian/Ubuntu: python3-venv)
• pip внутри создаваемого venv (устанавливается автоматически)

Использование

Запускайте из каталога, куда нужно положить папку docs/:

./py-export-api-docs.py requirements.txt
./py-export-api-docs.py /path/to/requirements.txt --recreate-venv
./py-export-api-docs.py requirements.txt --strict

Или через интерпретатор:

python3 py-export-api-docs.py requirements.txt

Опции

Опция	Описание
requirements	Путь к файлу requirements.txt (обязательный аргумент)
--venv-dir PATH	Каталог виртуального окружения. По умолчанию: /tmp/export-api-docs-<uid>-<hash>, где hash — SHA256 от текущей рабочей директории
--recreate-venv	Удалить и пересоздать venv, переустановить пакеты
--strict	Завершить с кодом 1, если хотя бы один пакет или модуль не удалось экспортировать

Результат

В текущей рабочей директории создаётся:

docs/
├── README.md          # индекс: таблица модулей и ссылок
├── <import-module>/
│   └── api.md         # документация модуля
└── ...

Для каждого пакета определяются корневые import-модули (из top_level.txt в метаданных дистрибутива, из встроенных fallback-таблиц или по эвристике). Каждый модуль экспортируется один раз, даже если несколько пакетов его предоставляют.

Поддерживаемые строки requirements.txt

Обрабатываются:

• PEP 508 спецификации имён пакетов (requests>=2.28, flask[async], с маркерами окружения после ;)
• Включения -r other.txt — только если файл лежит внутри дерева каталога, где находится корневой requirements.txt

Устанавливаются pip'ом, но не экспортируются (имя пакета не извлекается):

• -e (editable installs)
• Прямые URL и прочие pip-опции, начинающиеся с -

Кэширование venv

Переустановка пакетов пропускается, если:

• venv уже существует;
• хеш дерева requirements-файлов (все -r включения) совпадает с сохранённым в .requirements.sha256 внутри venv.

При изменении requirements.txt или включённых файлов зависимости переустанавливаются автоматически. Флаг --recreate-venv принудительно пересоздаёт окружение.

Коды выхода

Код	Причина
0	Документация экспортирована (в не-strict режиме допускаются предупреждения)
1	Файл requirements не найден; нет имён пакетов; ничего не экспортировано; или --strict и были ошибки

Предупреждения

Скрипт продолжает работу при частичных сбоях (без --strict):

• пакет не установился в venv;
• не удалось определить import-модуль;
• небезопасное имя модуля;
• ошибка pydoc-markdown при экспорте.

Для пакетов без top_level.txt используется guess по имени дистрибутива (my-package → my_lib) или встроенные соответствия (python-gitlab → gitlab, pyyaml → yaml, pillow → PIL и др.).

Пример вывода

Creating virtualenv: /tmp/export-api-docs-1000-a1b2c3d4e5f6
Installing packages into temporary virtualenv…
requests -> requests
  wrote docs/requests/api.md (42 KiB)
Done. Documentation in /home/user/project/docs