export_1c_help/SPEC_EXPORT_DOCS.md

Спецификация export_docs.py

Цель

Публикация аналитических Markdown-статей из рабочих каталогов проекта (docs/ и др.) в wiki-репозиторий (*.wiki.git) с:

• размещением в указанной папке wiki (--folder);
• сохранением структуры подкаталогов по маске;
• конвертацией локальных ссылок между выгружаемыми .md-файлами.

CLI

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] остаются рабочими, т.к. переопределения переписываются).