mihailkudravcev
78 lines
4.5 KiB
Markdown
78 lines
4.5 KiB
Markdown
# Спецификация `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)` и ``:
|
||
|
||
- внешние 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]` остаются рабочими, т.к. переопределения переписываются).
|