Add installed package version to exported API docs.

Write api-<version>.md with version metadata in each file and index, sanitize
output for safe paths/markdown, atomically replace exports, and add
--keep-old-versions to retain prior exports as an archive.

README.md

@@ -17,6 +17,7 @@
 ./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
+./py-export-api-docs.py requirements.txt --keep-old-versions
 ```
 
 Или через интерпретатор:
@@ -33,6 +34,7 @@ python3 py-export-api-docs.py requirements.txt
 | `--venv-dir PATH` | Каталог виртуального окружения. По умолчанию: `/tmp/export-api-docs-<uid>-<hash>`, где `hash` — SHA256 от текущей рабочей директории |
 | `--recreate-venv` | Удалить и пересоздать venv, переустановить пакеты |
 | `--strict` | Завершить с кодом 1, если хотя бы один пакет или модуль не удалось экспортировать |
+| `--keep-old-versions` | Не удалять предыдущие `api-<version>.md` и legacy `api.md` в каталогах модулей |
 
 ## Результат
 
@@ -40,12 +42,34 @@ python3 py-export-api-docs.py requirements.txt
 
 ```
 docs/
-├── README.md          # индекс: таблица модулей и ссылок
+├── README.md              # индекс текущего экспорта
 ├── <import-module>/
-│   └── api.md         # документация модуля
+│   ├── api-<version>.md   # документация модуля
+│   └── ...                # другие api-<version>.md — только с --keep-old-versions
 └── ...
 ```
 
+### Версия в файлах
+
+В каждом `api-<version>.md` в начале указаны имя пакета, **фактически установленная** версия (из метаданных venv, не из спецификатора в `requirements.txt`) и import-модуль:
+
+```markdown
+<!-- py-export-api-docs: package=requests version=2.32.3 module=requests -->
+
+> **Source:** `requests` **2.32.3** (import: `requests`)
+```
+
+Имя файла — filesystem-safe slug той же версии: небезопасные символы заменяются на `_` (например, `1.0+local` → `api-1.0+local.md`, `1.0 rc1` → `api-1.0_rc1.md`). В редких случаях разные строки версии могут дать один slug — тогда файл перезаписывается.
+
+### Очистка и архив
+
+| Режим | Поведение |
+|-------|-----------|
+| По умолчанию | После успешного экспорта удаляются другие `api-<version>.md` и legacy `api.md` в каталоге модуля |
+| `--keep-old-versions` | Старые файлы остаются на диске как архив |
+
+`docs/README.md` перезаписывается при каждом запуске и содержит только модули **текущего** экспорта — архивные файлы в индекс не попадают.
+
 Для каждого пакета определяются корневые import-модули (из `top_level.txt` в метаданных дистрибутива, из встроенных fallback-таблиц или по эвристике). Каждый модуль экспортируется один раз, даже если несколько пакетов его предоставляют.
 
 ## Поддерживаемые строки requirements.txt
@@ -85,7 +109,7 @@ docs/
 - небезопасное имя модуля;
 - ошибка `pydoc-markdown` при экспорте.
 
-Для пакетов без `top_level.txt` используется guess по имени дистрибутива (`my-package ` → `my_lib`) или встроенные соответствия (`python-gitlab` → `gitlab`, `pyyaml` → `yaml`, `pillow` → `PIL` и др.).
+Для пакетов без `top_level.txt` используется guess по имени дистрибутива (`my-package` → `my_package`) или встроенные соответствия (`python-gitlab` → `gitlab`, `pyyaml` → `yaml`, `pillow` → `PIL` и др.).
 
 ## Пример вывода
 
@@ -93,6 +117,14 @@ docs/
 Creating virtualenv: /tmp/export-api-docs-1000-a1b2c3d4e5f6
 Installing packages into temporary virtualenv…
 requests -> requests
-  wrote docs/requests/api.md (42 KiB)
+  wrote docs/requests/api-2.32.3.md (42 KiB)
 Done. Documentation in /home/user/project/docs
 ```
+
+Сгенерированный `docs/README.md`:
+
+```markdown
+| Module | Version | File |
+|--------|---------|------|
+| `requests` | `2.32.3` | [requests/api-2.32.3.md](requests/api-2.32.3.md) |
+```