export_1c_help/README.md

# export_1c_help

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

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

Дополнительно: публикация произвольных Markdown-статей в wiki через `export_docs.py` (спецификация: [`SPEC_EXPORT_DOCS.md`](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), типичная структура:

   ```text
   <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:

```bash
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
```

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

```text
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`:

```bash
# подмодуль
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 не определяется):

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

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

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

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

```bash
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. Снова:

```bash
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-документов

```bash
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>/…`.

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

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

```bash
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` | сообщение коммита |

---

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

```bash
# целевая 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
```

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

```bash
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 и тип данных.

```bash
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`).

```bash
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`:

```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