export_1c_help/SPEC_EXPORT_DOCS.md

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

Цель

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

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

CLI

python export_docs.py push \
  --files <glob> [<glob> ...] \
  [--folder <wiki/subfolder>] \
  [-s <path> | -c <path>] \
  [--wiki-url <repo.wiki.git>] [--remote origin] \
  [--work-dir <path>] [-o <path>] [--branch main] \
  [-m "commit message"] [--dry-run] [--verbose] \
  [--no-flat-root]

python export_docs.py clean \
  [--folder <wiki/subfolder>] \
  [-s <path> | -c <path>] \
  [--wiki-url <repo.wiki.git>] [--remote origin] \
  [--work-dir <path>] [--branch main] \
  [-m "commit message"] [--dry-run]

Параметры

• --files (только push, обяз.): одна или несколько 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 (опц., по умолчанию пусто = корень wiki): папка назначения, например docs или migration/docs.
• --wiki-url (опц.): явный wiki URL; если не указан — из git remote источника.
• --no-flat-root: оставить вложенные каталоги в wiki вместо имён folder__sub__file.md.
• --dry-run: сборка + подготовка clone, без git push.
• --verbose: печатать полный список входных аргументов --files.

clean удаляет страницы из manifest.export_docs.<hash(folder)>.json и блок <!-- export_docs:… --> в Home.md / _Sidebar.md. Параметр --files не используется.

Правила размещения файлов

1. Для каждой маски определяется статический префикс (часть до wildcard).
2. Для каждого совпавшего .md считается относительный путь от этого префикса.
3. В wiki файл размещается как:
   • flat (по умолчанию): <folder>__<path>__<name>.md (например docs/transfer/a.md → docs__transfer__a.md);
   • nested (--no-flat-root): <folder>/<relative-path-from-pattern-root>.

Примеры (flat):

• --files ./docs/**/*.md --folder docs
  • docs/plan.md → docs__plan.md
  • docs/transfer/mapping/x.md → docs__transfer__mapping__x.md

Индексы и навигация

• На каждую папку с выгруженными статьями (и/или исходным INDEX.md) генерируется страница …__INDEX (или …/INDEX.md в nested-режиме).
• В индексе: ссылка на родителя, список подпапок, список статей с полными заголовками (H1).
• Исходный INDEX.md папки не дублируется как отдельная статья в списке — его тело (без ведущего H1) вшивается в автоиндекс.
• В обычных статьях добавляется блок «вернуться в индекс папки».
• В Home.md / _Sidebar.md вставляется/обновляется блок между маркерами export_docs:begin / export_docs:end.
• _Sidebar: дерево папок в порядке родителя → дети (DFS); подпись — только имя сегмента (📁 mapping), без слова «Папка» и без полного пути.

Конвертация ссылок

Для Markdown-ссылок вида [text](target) и ![alt](target):

• внешние URL (http(s), mailto, ftp), якоря #..., абсолютные /... — без изменений;
• относительные ссылки на выгружаемые .md пересчитываются на целевой путь в wiki; в Markdown-цели суффикс .md опускается (Gitea: /wiki/page, не /wiki/page.md);
• цели URL-кодируются (пробелы, скобки, кириллица);
• локальные ссылки на файлы вне выгрузки, но внутри git-репозитория источника, переписываются в https://…/src/branch/<branch>/<relpath>;
• прочие локальные файлы, попавшие в выгрузку как вложения, копируются, ссылки пересчитываются.

Rewrite поддерживает inline и reference-style ([id]: target).

Управление удалениями (без потери чужих wiki-страниц)

Manifest в корне wiki clone: manifest.export_docs.<hash(folder)>.json.

При следующем push для того же --folder:

• файлы из предыдущего manifest, которых нет в новой выгрузке, удаляются;
• статьи/файлы, не управляемые этим manifest, не трогаются.

Перед git add снимаются флаги assume-unchanged / skip-worktree с Home.md и _Sidebar.md (иначе Gitea-клон может не закоммитить правки навигации).

Ограничения текущей версии

• Источники выгрузки — только .md.
• Вложения копируются только если на них есть локальная ссылка в выгружаемом Markdown.
• Монтирование чужого дерева в подпапку wiki одной маской вида ws:./ws-rhana/docs/** пока не реализовано — используйте отдельные --files / --folder или ссылки на src/branch/….