Track configuration version and page lifecycle in wiki export.
Record created/edited/deleted-in versions per page; add History.md and update workflow docs.
This commit is contained in:
mihailkudravcev
@@ -1,6 +1,6 @@
|
||||
# export_1c_help
|
||||
|
||||
**Версия:** см. [`VERSION`](VERSION) (текущая: **0.1.0**) · [CHANGELOG](CHANGELOG.md)
|
||||
**Версия:** см. [`VERSION`](VERSION) (текущая: **0.2.0**) · [CHANGELOG](CHANGELOG.md)
|
||||
**Лицензия:** [MIT](LICENSE)
|
||||
|
||||
Выгрузка встроенной справки конфигурации 1С (`**/Ext/Help/ru.html`) в Markdown и публикация в [Gitea Wiki](https://docs.gitea.com/usage/wiki).
|
||||
@@ -9,26 +9,66 @@
|
||||
|
||||
---
|
||||
|
||||
## Порядок обновления wiki (после доработки справки в конфигурации)
|
||||
|
||||
Инструмент **всегда** пересобирает wiki из всего `src/` (инкрементального патча нет). Частичная правка Help в конфигураторе → полная перевыгрузка `src` → полный `push`.
|
||||
|
||||
1. Доработать справку в конфигураторе (нужные объекты/формы).
|
||||
2. Выгрузить конфигурацию в git (`crm3-26/`) и закоммитить/запушить, как обычно.
|
||||
3. В монорепо: `git pull` (актуальный `crm3-26/src`, в т.ч. `VERSION` / `Configuration.xml`).
|
||||
4. Синхронизировать wiki:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
Перед записью можно проверить без push:
|
||||
|
||||
```bash
|
||||
python3 export_1c_help.py push \
|
||||
-s ../../crm3-26/src \
|
||||
--wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
**Канон текста** — HTML в конфигурации. Ручные правки страниц в wiki сотрутся при следующем `push` (если не указан `--keep-unmanaged`).
|
||||
|
||||
---
|
||||
|
||||
## Версии конфигурации на страницах
|
||||
|
||||
| Где | Что фиксируется |
|
||||
|-----|-----------------|
|
||||
| `Home.md` | версия конфигурации **этой** выгрузки |
|
||||
| подвал каждой страницы | версия выгрузки; **создана в** / **изменена в** |
|
||||
| `History.md` | сводка +/−/~ и накопительный список **удалённых** (`deleted_in`) |
|
||||
| `manifest.json` | те же поля + `content_hash`, история `exports[]` |
|
||||
|
||||
Версия берётся из `<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
|
||||
|
||||
# конвертация + push в wiki-репозиторий Gitea
|
||||
python3 export_1c_help.py push \
|
||||
-s ../../crm3-26/src \
|
||||
--wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git \
|
||||
-o ./out/wiki-md
|
||||
--wiki-url https://git.p7net.ru/1c/crm3_26.wiki.git
|
||||
```
|
||||
|
||||
Проверка версии:
|
||||
|
||||
```bash
|
||||
python3 export_1c_help.py --version
|
||||
```
|
||||
@@ -39,62 +79,30 @@ python3 export_1c_help.py --version
|
||||
|
||||
### `convert`
|
||||
|
||||
Читает `src/`, пишет Markdown-дерево wiki:
|
||||
|
||||
| Файл | Назначение |
|
||||
|------|------------|
|
||||
| `Home.md` | оглавление по типам метаданных |
|
||||
| `_Sidebar.md` | боковая навигация (объекты без форм) |
|
||||
| `«Заголовок».md` / `%D0%….md` | страницы справки (кириллица в git — **percent-encoded**, как хранит Gitea) |
|
||||
| `manifest.json` | карта `meta_key` → title / filename |
|
||||
|
||||
| Параметр | Описание |
|
||||
|----------|----------|
|
||||
| `-s` / `--src` | каталог `src` выгрузки конфигурации |
|
||||
| `-o` / `--out` | каталог результата |
|
||||
| `--objects-only` | без справки форм (`Forms/*/Ext/Help`) |
|
||||
| `--objects-only` | без справки форм |
|
||||
| `--keep-empty` | не пропускать почти пустые страницы |
|
||||
| `--clean` | очистить `--out` перед записью (кроме `.git`) |
|
||||
| `--clean` | очистить `--out` перед записью |
|
||||
| `--prev-manifest` | предыдущий `manifest.json` (lifecycle) |
|
||||
| `--config-version` | явная версия конфигурации |
|
||||
|
||||
### `push`
|
||||
|
||||
Выполняет `convert`, затем `git clone` / обновление wiki-репозитория (обычно `*.wiki.git`), коммит и `git push`.
|
||||
`prepare wiki` → `convert` (с `manifest.json` из wiki) → `git commit` / `push`.
|
||||
|
||||
| Параметр | Описание |
|
||||
|----------|----------|
|
||||
| `--wiki-url` | URL wiki git, напр. `https://git.p7net.ru/1c/crm3_26.wiki.git` |
|
||||
| `--work-dir` | локальный clone wiki |
|
||||
| `--wiki-url` | URL `*.wiki.git` |
|
||||
| `--dry-run` | только convert |
|
||||
| `--keep-unmanaged` | не удалять чужие `.md` в wiki |
|
||||
| `--keep-unmanaged` | не удалять чужие `.md` |
|
||||
| `-m` / `--message` | сообщение коммита |
|
||||
|
||||
Для `push` нужны права записи в wiki (HTTPS + credential helper / token).
|
||||
|
||||
---
|
||||
|
||||
## Как устроены ссылки
|
||||
|
||||
В HTML справки 1С:
|
||||
|
||||
```text
|
||||
Catalog.ВидыНоменклатуры/Help
|
||||
Document.ЗаказКлиента.Form.ФормаДокумента/Help
|
||||
```
|
||||
|
||||
В wiki:
|
||||
|
||||
```markdown
|
||||
[[Виды номенклатуры]]
|
||||
[[текст|Виды номенклатуры]]
|
||||
```
|
||||
|
||||
Ключ метаданных (`Catalog.ВидыНоменклатуры`) стабилен и пишется в подвал страницы и в `manifest.json`.
|
||||
|
||||
---
|
||||
|
||||
## Репозиторий
|
||||
|
||||
Отдельный git-репозиторий (подмодуль монорепозитория миграции):
|
||||
|
||||
- путь в дереве проекта: `tools/export_1c_help/`
|
||||
- remote (ожидаемый): `https://git.p7net.ru/tools/export_1c_help.git`
|
||||
- путь: `tools/export_1c_help/`
|
||||
- remote: https://git.p7net.ru/tools/export_1c_help.git
|
||||
|
||||
Reference in New Issue
Block a user