export_1c_help/README.md

export_1c_help

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

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

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

Также: HTML/текстовые прототипы управляемых форм — form_xml_to_html.py (v0.2.3, Michael BAG mk@p7net.ru).

Зависимости: 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

---

HTML-прототипы форм (form_xml_to_html.py)

Скрипт v0.2.3, автор Michael BAG mk@p7net.ru.

Собирает интерактивный HTML и/или текстовое дерево/макет по Ext/Form.xml. В placeholder полей: DataPath и тип данных.

cd tools/export_1c_help

# HTML в каталог-структуру
python3 form_xml_to_html.py \
  -b crm3-26 \
  -o Справочник.Номенклатура \
  -f ФормаЭлемента \
  -p out/form-prototypes

# HTML в один файл + дерево элементов внутри страницы
python3 form_xml_to_html.py \
  -b crm3-26.rhana \
  -o Общие \
  -f РК_ФормаНастроекРана \
  -O /tmp/РК_ФормаНастроекРана.html \
  -T

# только консоль: дерево и ASCII-макет
python3 form_xml_to_html.py \
  -c configs/form_prototype.crm3-26.rhana.json \
  -f РК_ФормаНастроекРана \
  -T -M

# текстовый файл без HTML
python3 form_xml_to_html.py \
  -b crm3-26.rhana -o Общие -f РК_ФормаНастроекРана \
  -T -M -t -O /tmp/form.txt

Параметр	Описание
-b / --base	имя/путь каталога конфигурации (или её src/)
-o / --object	Справочник.Номенклатура, Документ.X, … или Общие
-f / --form	имя формы
-p / --out-path	корень вывода HTML: <out>/<конфа>/<тип>/<объект>/<форма>.html
-O / --out-file	файл вывода, если нет -p (HTML или текст при -t)
-T / --elements-tree	дерево элементов
-M / --text-maket	текстовый макет «как в окне»
-t / --text-only	в -O только текст, без HTML
-c / --config	JSON с base, object, out_path/out_file, search_roots (без формы)

Правила вывода:

• нет -O → -T/-M в консоль;
• есть -O (без -t) → HTML в файл, при -T/-M блоки добавляются на страницу;
• -t + -O → текстовый файл как в консоли;
• без -p/-O и без -T/-M — ошибка (нужен явный вывод).

Пример HTML-пути при -p:

out/form-prototypes/crm3-26/Справочники/Номенклатура/ФормаЭлемента.html.

---

Wiki: все формы (form_wiki_export.py)

Полный обход **/Ext/Form.xml в одной или нескольких конфигурациях, генерация HTML и wiki-страниц с настраиваемым префиксом (по умолчанию form_, в конфиге crm3-26 — forms_) для просмотра в Gitea wiki (iframe + HTML-вложение).

Обновление не затирает другие wiki-страницы: используется отдельный manifest manifest.export_forms.json и маркеры <!-- export_forms:begin/end --> (не пересекаются с export_docs и справкой export_1c_help).

cd tools/export_1c_help

# локальная сборка (без push)
python3 form_wiki_export.py build -b crm3-26.rhana -o out/form-wiki-rhana

# другой префикс (переопределяет JSON)
python3 form_wiki_export.py build -c configs/form_wiki.crm3-26.json --wiki-prefix form_

# сборка + push в wiki (dry-run сначала)
python3 form_wiki_export.py push -c configs/form_wiki.crm3-26.json --dry-run
python3 form_wiki_export.py push -c configs/form_wiki.crm3-26.json

# только расширение
python3 form_wiki_export.py push -b crm3-26.rhana

# удалить form_* из wiki
python3 form_wiki_export.py clean --wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git

Команда	Описание
build	собрать {prefix}*.md + {prefix}*.html + {prefix}INDEX.md локально
push	build + git push в wiki
clean	удалить ранее опубликованные страницы по manifest

Имена страниц: {prefix}{конфа}__{тип RU}__{объект}__{форма}.md (для общих форм — {prefix}{конфа}__Общие_формы__{форма}.md). Тип — русское имя из метаданных (Справочники, Документы, Обработки, …); пробелы в типе заменяются на _.

Приоритет префикса: --wiki-prefix → wiki_prefix в JSON → form_. Если в значении нет завершающего _, он добавляется (forms → forms_).

Конфиг configs/form_wiki.crm3-26.json:

{
  "bases": ["crm3-26"],
  "search_roots": ["../.."],
  "out_path": "out/form-wiki",
  "wiki_url": "https://git.p7net.ru/1c/crm3_26.wiki.git",
  "wiki_prefix": "forms_"
}

---

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

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