export_1c_help/README.md

export_1c_help

Версия: см. VERSION (текущая: 0.3.12) · CHANGELOG
Лицензия: MIT

Выгрузка встроенной справки любой конфигурации 1С (**/Ext/Help/ru.html) в Markdown и публикация в wiki git-репозитория (Gitea / GitLab: *.wiki.git).

Дополнительно: публикация произвольных Markdown-статей в wiki через export_docs.py (спецификация: SPEC_EXPORT_DOCS.md).

Зависимости: Python 3.10+, только стандартная библиотека.

---

Подключение произвольной конфигурации к wiki

Инструмент не привязан к crm3-26. Источник — каталог выгрузки конфигурации (подмодуль или корневой git-проект). Цель — wiki этого репозитория либо любой другой *.wiki.git.

1. Подготовка репозитория конфигурации

1. Конфигурация лежит в git (отдельный репозиторий или submodule), типичная структура:

   <config-root>/
     VERSION                 # опционально
     src/
       Configuration.xml
       Catalogs/…/Ext/Help/ru.html
       …
   

2. На сервере (Gitea / GitLab) у репозитория конфигурации включена Wiki.

3. Убедитесь, что у вас есть права push в wiki (…/repo.wiki.git).
   Первый push создаст/обновит страницы; на Gitea wiki должна быть уже инициализирована (хотя бы пустая/одна страница через UI, если сервер так требует).

Проверка путей и URL:

cd tools/export_1c_help   # или путь к клону export_1c_help

# подмодуль в монорепо
python3 export_1c_help.py info -c ../../crm3-26

# корневой клон конфигурации
python3 export_1c_help.py info -c /path/to/my_config

# только src
python3 export_1c_help.py info -s /path/to/my_config/src

Пример вывода:

config_root:     …/crm3-26
src:             …/crm3-26/src
config_version:  3.1.36.33
git_remote(origin): https://git.p7net.ru/1c/crm3_26.git
wiki_url:        https://git.p7net.ru/1c/crm3_26.wiki.git

Правило авто-URL: https://host/org/repo.git → https://host/org/repo.wiki.git
(аналогично для git@host:org/repo.git).

2. Первая выгрузка в wiki репозитория конфигурации

Без --wiki-url цель берётся из origin git-репозитория, которому принадлежит -c / -s:

# подмодуль
python3 export_1c_help.py push -c ../../crm3-26

# любой другой корень / submodule
python3 export_1c_help.py push -c /path/to/other_config

# dry-run (только сборка MD, без push)
python3 export_1c_help.py push -c ../../crm3-26 --dry-run

Промежуточные каталоги по умолчанию (чтобы не смешивать конфигурации):

• out/wiki-md-<имя-корня>/
• out/wiki_clone-<имя-корня>/

3. Выгрузка в произвольный wiki

Если wiki не у того же репозитория (или remote не определяется):

python3 export_1c_help.py push \
  -c /path/to/config \
  --wiki-url https://git.example/org/docs.wiki.git

Можно указать и URL кода — он будет преобразован в .wiki.git:

python3 export_1c_help.py push \
  -c /path/to/config \
  --wiki-url https://git.example/org/docs.git

Другой remote (не origin):

python3 export_1c_help.py push -c /path/to/config --remote upstream

4. Обновление после доработки справки в конфигураторе

Инструмент всегда пересобирает wiki из всего src/ (инкремента нет).

1. Доработать Help в конфигураторе.
2. Выгрузить конфигурацию в её git-репозиторий (git commit / push).
3. Обновить рабочую копию (git pull / git submodule update).
4. Снова:

python3 export_1c_help.py push -c /path/to/config

Канон текста справки — HTML в конфигурации: страницы, попавшие в manifest.json, при push перезаписываются.
Пользовательские статьи wiki (не из выгрузки Help) сохраняются. Полная очистка wiki — только с --wipe-unmanaged.

---

Версии конфигурации на страницах

Где	Что
Home.md	наименование, версия, разработчик этой выгрузки
подвал страницы	конфигурация, версия, разработчик; создана в / изменена в
History.md	сводка +/-/~ и удалённые (deleted_in)
manifest.json	lifecycle + content_hash + exports[]

Версия: <config>/VERSION или <Version> в Configuration.xml (--config-version перекрывает).

При push предыдущий manifest.json читается из целевой wiki автоматически.

---

Команды

Команда	Назначение
info	пути, версия, remote, wiki URL
convert	только Markdown на диск
push	convert + commit/push в wiki

Публикация произвольных Markdown-документов

python3 export_docs.py push \
  --files ./docs/**/*.md \
  --folder docs

Если -s / -c не указаны, wiki URL берётся из git remote текущей папки.

По умолчанию имена страниц плоские (docs__transfer__mapping__file.md) — так Gitea wiki открывает страницы, где вложенные /wiki/docs/... дают 404. Отключить: --no-flat-root.

Что делает push:

• выгружает .md и вложения по локальным ссылкам ([](...), ![](...), reference-style [id]: target);
• для каждой папки с статьями собирает …__INDEX (статьи + подпапки); исходный INDEX.md папки вшивается в эту страницу;
• в каждой статье — ссылка «вернуться в индекс папки»;
• обновляет блок навигации в Home / _Sidebar (иерархия папок DFS, подписи вида 📁 meta без полного пути);
• внутренние wiki-ссылки без суффикса .md; ссылки на файлы репозитория вне выгрузки → URL …/src/branch/<branch>/….

python3 export_docs.py push \
  --files ./docs/**/*.md \
  -s /path/to/config/src \
  --folder migration/docs

Очистка опубликованных export_docs-страниц из wiki:

python3 export_docs.py clean \
  --folder docs \
  --wiki-url https://git.example/org/repo.wiki.git

clean не принимает --files: удаление идёт по сохранённому manifest.export_docs.*.json для указанного --folder (и убирает блок export_docs из Home / _Sidebar).

Общие параметры источника (взаимоисключающие):

Параметр	Описание
-c / --config	корень конфигурации (…/crm3-26) или её src/
-s / --src	явно каталог src

Параметр	Описание
--wiki-url	явный wiki (иначе из git remote конфигурации)
--remote	имя remote для авто-URL (origin)
--objects-only	без справки форм
--dry-run	без git push
--wipe-unmanaged	стереть и пользовательские статьи wiki (по умолчанию они сохраняются)
--prev-manifest	свой предыдущий manifest
--config-version	явная версия
-m / --message	сообщение коммита

---

Примеры для монорепозитория миграции

# целевая crm3-26 → её wiki
python3 export_1c_help.py push -c ../../crm3-26

# исходная crm3-dev → её wiki (если wiki включена у crm3_old)
python3 export_1c_help.py push -c ../../crm3-dev

# расширение — только если в выгрузке есть Ext/Help
python3 export_1c_help.py info -c ../../crm3-26.rhana

Только локальная конвертация:

python3 export_1c_help.py convert -c ../../crm3-26 -o ./out/wiki-md-crm3-26 --clean

---

Репозиторий инструмента

• путь в монорепо: tools/export_1c_help/
• remote: https://git.p7net.ru/tools/export_1c_help.git