# export_1c_help

**Версия:** см. [`VERSION`](VERSION) (текущая: **0.3.12**) · [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)).

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

---

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

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