# py-export-api-docs

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

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

## Требования

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

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

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

```bash
./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
```

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

```bash
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
```