Support any 1C config dump and auto wiki URL from its git remote.

Add info command, -c/--config, derived repo.wiki.git target, and README for submodule/root workflows.
2026-07-23 15:24:59 +03:00
parent ecddcef586
commit 02a05d34d0
5 changed files with 417 additions and 120 deletions
@@ -1,108 +1,187 @@
 # export_1c_help

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

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

 Зависимости: **Python 3.10+**, только стандартная библиотека.

 ---

-## Порядок обновления wiki (после доработки справки в конфигурации)
+## Подключение произвольной конфигурации к wiki

-Инструмент **всегда** пересобирает wiki из всего `src/` (инкрементального патча нет). Частичная правка Help в конфигураторе → полная перевыгрузка `src` → полный `push`.
+Инструмент не привязан к `crm3-26`. Источник — каталог выгрузки конфигурации (подмодуль или корневой git-проект). Цель — wiki **этого** репозитория либо любой другой `*.wiki.git`.

-1. Доработать справку в конфигураторе (нужные объекты/формы).
-2. Выгрузить конфигурацию в git (`crm3-26/`) и закоммитить/запушить, как обычно.
-3. В монорепо: `git pull` (актуальный `crm3-26/src`, в т.ч. `VERSION` / `Configuration.xml`).
-4. Синхронизировать wiki:
+### 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
-python3 export_1c_help.py push \
-  -s ../../crm3-26/src \
-  --wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git \
-  -m "sync help after config update"
+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
 ```

-Перед записью можно проверить без push:
+Пример вывода:
+
+```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 \
-  -s ../../crm3-26/src \
-  --wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git \
-  --dry-run
+  -c /path/to/config \
+  --wiki-url https://git.example/org/docs.wiki.git
 ```

-**Канон текста** — HTML в конфигурации. Ручные правки страниц в wiki сотрутся при следующем `push` (если не указан `--keep-unmanaged`).
+Можно указать и 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` | те же поля + `content_hash`, история `exports[]` |
+| подвал страницы | версия выгрузки; **создана в** / **изменена в** |
+| `History.md` | сводка +/−/~ и удалённые (`deleted_in`) |
+| `manifest.json` | lifecycle + `content_hash` + `exports[]` |

-Версия берётся из `<config>/VERSION` или `<Version>` в `Configuration.xml` (можно переопределить `--config-version`).
+Версия: `<config>/VERSION` или `<Version>` в `Configuration.xml` (`--config-version` перекрывает).

-Жизненный цикл считается относительно предыдущего `manifest.json` в wiki (при `push` подтягивается автоматически).
-
---
-
-## Быстрый старт
-
-```bash
-cd tools/export_1c_help
-
-python3 export_1c_help.py convert \
-  -s ../../crm3-26/src \
-  -o ./out/wiki-md \
-  --clean
-
-python3 export_1c_help.py push \
-  -s ../../crm3-26/src \
-  --wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git
-```
-
-```bash
-python3 export_1c_help.py --version
-```
+При `push` предыдущий `manifest.json` читается из целевой wiki автоматически.

 ---

 ## Команды

-### `convert`
+| Команда | Назначение |
+|---------|------------|
+| `info` | пути, версия, remote, wiki URL |
+| `convert` | только Markdown на диск |
+| `push` | convert + commit/push в wiki |
+
+Общие параметры источника (взаимоисключающие):

 | Параметр | Описание |
 |----------|----------|
-| `-s` / `--src` | каталог `src` выгрузки конфигурации |
-| `-o` / `--out` | каталог результата |
+| `-c` / `--config` | корень конфигурации (`…/crm3-26`) **или** её `src/` |
+| `-s` / `--src` | явно каталог `src` |
+
+| Параметр | Описание |
+|----------|----------|
+| `--wiki-url` | явный wiki (иначе из git remote конфигурации) |
+| `--remote` | имя remote для авто-URL (`origin`) |
 | `--objects-only` | без справки форм |
-| `--keep-empty` | не пропускать почти пустые страницы |
-| `--clean` | очистить `--out` перед записью |
-| `--prev-manifest` | предыдущий `manifest.json` (lifecycle) |
-| `--config-version` | явная версия конфигурации |
-
-### `push`
-
-`prepare wiki` → `convert` (с `manifest.json` из wiki) → `git commit` / `push`.
-
-| Параметр | Описание |
-|----------|----------|
-| `--wiki-url` | URL `*.wiki.git` |
-| `--dry-run` | только convert |
-| `--keep-unmanaged` | не удалять чужие `.md` |
-| `-m` / `--message` | сообщение коммита |
+| `--dry-run` | без git push |
+| `--prev-manifest` | свой предыдущий manifest |
+| `--config-version` | явная версия |

 ---

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

- путь: `tools/export_1c_help/`
+```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