export_1c_help/README.md

# export_1c_help

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

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

Зависимости: **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 в конфигурации. Ручные правки wiki сотрутся при следующем `push` (если нет `--keep-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 |

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

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

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

---

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

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