tools/export_1c_help
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
export_1c_help/README.md
T
mihailkudravcev a2c68fa5d5 docs: sync README and SPEC_EXPORT_DOCS with export_docs 0.3.12 
Document flat-root pages, indexes, sidebar DFS tree, and link rewriting.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-29 13:48:37 +03:00

230 lines
9.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
Reference in New Issue View Git Blame Copy Permalink