Release 0.3.9: export_docs clean + wiki index pages

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-29 13:10:46 +03:00
parent 7dd699dab5
commit 3d272b46c7
7 changed files with 1095 additions and 20 deletions
@@ -0,0 +1,77 @@
+# Спецификация `export_docs.py`
+
+## Цель
+
+Публикация аналитических Markdown-статей из рабочих каталогов проекта (`docs/` и др.) в wiki-репозиторий (`*.wiki.git`) с:
+
+- размещением в указанной папке wiki (`--folder`);
+- сохранением структуры подкаталогов по маске;
+- конвертацией локальных ссылок между выгружаемыми `.md`-файлами.
+
+## CLI
+
+```bash
+python export_docs.py push \
+  --files <glob> [<glob> ...] \
+  -s <path-to-src-or-config> \
+  --folder <wiki/subfolder> \
+  [--wiki-url <repo.wiki.git>] [--remote origin] \
+  [--work-dir <path>] [-o <path>] [--branch main] \
+  [-m "commit message"] [--dry-run]
+```
+
+## Параметры
+
+- `--files` (обяз.): одна или несколько glob-масок.
+  - Экспортируются только `.md`.
+  - Если маска указывает на каталог — берутся `**/*.md`.
+  - Пример: `./docs/*.md`, `./docs/**/*.md`, `./reports`.
+- `-s/--src` или `-c/--config` (опц.): путь к конфигурации/`src` только для определения wiki URL по remote (аналогично `export_1c_help.py`).
+  - Если не указаны, анализируется текущая папка: берётся git remote текущей папки и из неё выводится `*.wiki.git`.
+- `--folder` (опц., по умолчанию `docs`): папка назначения в wiki, например `docs` или `migration/docs`.
+- `--wiki-url` (опц.): явный wiki URL; если не указан, выводится из `git remote` источника.
+- `--dry-run`: сборка + подготовка clone, без `git push`.
+
+## Правила размещения файлов
+
+1. Для каждой маски определяется статический префикс (часть до wildcard).
+2. Для каждого совпавшего `.md` считается относительный путь от этого префикса.
+3. В wiki файл размещается как:
+   - `<folder>/<relative-path-from-pattern-root>`.
+
+Примеры:
+
+- `--files ./docs/*.md --folder docs`
+  - `docs/a.md` → `docs/a.md`
+- `--files ./docs/**/*.md --folder migration/docs`
+  - `docs/plan.md` → `migration/docs/plan.md`
+  - `docs/phases/p1.md` → `migration/docs/phases/p1.md`
+
+## Конвертация ссылок
+
+Для Markdown-ссылок вида `[text](target)` и `![alt](target)`:
+
+- внешние URL (`http(s)`, `mailto`, `ftp`), якоря `#...`, абсолютные `/...` — без изменений;
+- относительные ссылки на выгружаемые `.md` пересчитываются на новый относительный путь между целевыми файлами в wiki;
+- ссылки на невыгружаемые файлы остаются как есть.
+
+Цель: сохранить ссылочность внутри набора опубликованных статей.
+
+## Управление удалениями (без потери чужих wiki-страниц)
+
+Используется отдельный manifest для `export_docs` в корне wiki clone:
+
+- `manifest.export_docs.<hash(folder)>.json`.
+
+При следующем запуске для того же `--folder`:
+
+- файлы из предыдущего manifest, которых нет в новой выгрузке, удаляются;
+- статьи/файлы, не управляемые этим manifest, не трогаются.
+
+## Ограничения текущей версии
+
+- Автоматически обрабатываются только `.md` как источники выгрузки.
+- Вложения (картинки/файлы), на которые есть локальные ссылки в `[](...)` / `![](...)`, **копируются** в wiki вместе со статьями (с сохранением структуры каталогов относительно статического префикса маски).
+- Rewrite поддерживает как:
+  - inline-ссылки/картинки: `[](...)` и `![](...)`;
+  - reference-style определения: `[id]: target` (то есть ссылки вида `[text][id]` остаются рабочими, т.к. переопределения переписываются).