mihailkudravcev
188 lines
6.9 KiB
Markdown
188 lines
6.9 KiB
Markdown
# 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
|