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>
This commit is contained in:
mihailkudravcev
@@ -8,6 +8,11 @@ All notable changes to **export_1c_help** are documented in this file.
|
||||
|
||||
- `_Sidebar` folder tree: list subfolders under their real parent (DFS), not as a flat sort by depth (which made e.g. `transfer/mapping` appear under `ws`).
|
||||
|
||||
### Docs
|
||||
|
||||
- README: version **0.3.12**; `export_docs` section covers flat-root naming, folder indexes, Home/`_Sidebar` navigation, link rules, `clean`.
|
||||
- `SPEC_EXPORT_DOCS.md` aligned with current CLI and behaviour (0.3.9–0.3.12).
|
||||
|
||||
## [0.3.11] - 2026-07-29
|
||||
|
||||
### Fixed
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# export_1c_help
|
||||
|
||||
**Версия:** см. [`VERSION`](VERSION) (текущая: **0.3.9**) · [CHANGELOG](CHANGELOG.md)
|
||||
**Версия:** см. [`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)).
|
||||
Дополнительно: публикация произвольных Markdown-статей в wiki через `export_docs.py` (спецификация: [`SPEC_EXPORT_DOCS.md`](SPEC_EXPORT_DOCS.md)).
|
||||
|
||||
Зависимости: **Python 3.10+**, только стандартная библиотека.
|
||||
|
||||
@@ -149,15 +149,21 @@ python3 export_1c_help.py push -c /path/to/config
|
||||
|
||||
```bash
|
||||
python3 export_docs.py push \
|
||||
--files ./docs/*.md \
|
||||
--files ./docs/**/*.md \
|
||||
--folder docs
|
||||
```
|
||||
|
||||
Если `-s/ -c` не указаны, wiki URL берётся из git remote текущей папки.
|
||||
Если `-s` / `-c` не указаны, wiki URL берётся из git remote текущей папки.
|
||||
|
||||
Выгружаются только `.md`, но если внутри них есть локальные ссылки на файлы (картинки/документы), эти файлы тоже копируются в wiki и относительные ссылки сохраняются. Поддерживаются и reference-style ссылки через `[id]: target` (для `[text][id]` переопределения переписываются).
|
||||
По умолчанию имена страниц **плоские** (`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 \
|
||||
@@ -174,7 +180,7 @@ python3 export_docs.py clean \
|
||||
--wiki-url https://git.example/org/repo.wiki.git
|
||||
```
|
||||
|
||||
`clean` не принимает `--files`: удаление идёт по сохранённому `manifest.export_docs.*.json` для указанного `--folder`.
|
||||
`clean` не принимает `--files`: удаление идёт по сохранённому `manifest.export_docs.*.json` для указанного `--folder` (и убирает блок `export_docs` из `Home` / `_Sidebar`).
|
||||
|
||||
Общие параметры источника (взаимоисключающие):
|
||||
|
||||
|
||||
+48
-27
@@ -5,73 +5,94 @@
|
||||
Публикация аналитических Markdown-статей из рабочих каталогов проекта (`docs/` и др.) в wiki-репозиторий (`*.wiki.git`) с:
|
||||
|
||||
- размещением в указанной папке wiki (`--folder`);
|
||||
- сохранением структуры подкаталогов по маске;
|
||||
- конвертацией локальных ссылок между выгружаемыми `.md`-файлами.
|
||||
- сохранением логической структуры подкаталогов (по умолчанию — плоские имена файлов);
|
||||
- конвертацией локальных ссылок между выгружаемыми `.md` и вложениями;
|
||||
- автоиндексами папок и навигацией в `Home` / `_Sidebar`.
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
python export_docs.py push \
|
||||
--files <glob> [<glob> ...] \
|
||||
-s <path-to-src-or-config> \
|
||||
--folder <wiki/subfolder> \
|
||||
[--folder <wiki/subfolder>] \
|
||||
[-s <path> | -c <path>] \
|
||||
[--wiki-url <repo.wiki.git>] [--remote origin] \
|
||||
[--work-dir <path>] [-o <path>] [--branch main] \
|
||||
[-m "commit message"] [--dry-run] [--verbose] \
|
||||
[--no-flat-root]
|
||||
|
||||
python export_docs.py clean \
|
||||
[--folder <wiki/subfolder>] \
|
||||
[-s <path> | -c <path>] \
|
||||
[--wiki-url <repo.wiki.git>] [--remote origin] \
|
||||
[--work-dir <path>] [--branch main] \
|
||||
[-m "commit message"] [--dry-run]
|
||||
```
|
||||
|
||||
## Параметры
|
||||
|
||||
- `--files` (обяз.): одна или несколько glob-масок.
|
||||
- `--files` (только `push`, обяз.): одна или несколько glob-масок.
|
||||
- Экспортируются только `.md`.
|
||||
- Если маска указывает на каталог — берутся `**/*.md`.
|
||||
- Пример: `./docs/*.md`, `./docs/**/*.md`, `./reports`.
|
||||
- `-s/--src` или `-c/--config` (опц.): путь к конфигурации/`src` только для определения wiki URL по remote (аналогично `export_1c_help.py`).
|
||||
- Если не указаны, анализируется текущая папка: берётся git remote текущей папки и из неё выводится `*.wiki.git`.
|
||||
- `--folder` (опц., по умолчанию `docs`): папка назначения в wiki, например `docs` или `migration/docs`.
|
||||
- `--wiki-url` (опц.): явный wiki URL; если не указан, выводится из `git remote` источника.
|
||||
- Если не указаны, анализируется текущая папка: берётся git remote и из него выводится `*.wiki.git`.
|
||||
- `--folder` (опц., по умолчанию пусто = корень wiki): папка назначения, например `docs` или `migration/docs`.
|
||||
- `--wiki-url` (опц.): явный wiki URL; если не указан — из `git remote` источника.
|
||||
- `--no-flat-root`: оставить вложенные каталоги в wiki вместо имён `folder__sub__file.md`.
|
||||
- `--dry-run`: сборка + подготовка clone, без `git push`.
|
||||
- `--verbose`: печатать полный список входных аргументов `--files`.
|
||||
|
||||
`clean` удаляет страницы из `manifest.export_docs.<hash(folder)>.json` и блок `<!-- export_docs:… -->` в `Home.md` / `_Sidebar.md`. Параметр `--files` не используется.
|
||||
|
||||
## Правила размещения файлов
|
||||
|
||||
1. Для каждой маски определяется статический префикс (часть до wildcard).
|
||||
2. Для каждого совпавшего `.md` считается относительный путь от этого префикса.
|
||||
3. В wiki файл размещается как:
|
||||
- `<folder>/<relative-path-from-pattern-root>`.
|
||||
- **flat (по умолчанию):** `<folder>__<path>__<name>.md` (например `docs/transfer/a.md` → `docs__transfer__a.md`);
|
||||
- **nested (`--no-flat-root`):** `<folder>/<relative-path-from-pattern-root>`.
|
||||
|
||||
Примеры:
|
||||
Примеры (flat):
|
||||
|
||||
- `--files ./docs/*.md --folder docs`
|
||||
- `docs/a.md` → `docs/a.md`
|
||||
- `--files ./docs/**/*.md --folder migration/docs`
|
||||
- `docs/plan.md` → `migration/docs/plan.md`
|
||||
- `docs/phases/p1.md` → `migration/docs/phases/p1.md`
|
||||
- `--files ./docs/**/*.md --folder docs`
|
||||
- `docs/plan.md` → `docs__plan.md`
|
||||
- `docs/transfer/mapping/x.md` → `docs__transfer__mapping__x.md`
|
||||
|
||||
## Индексы и навигация
|
||||
|
||||
- На каждую папку с выгруженными статьями (и/или исходным `INDEX.md`) генерируется страница `…__INDEX` (или `…/INDEX.md` в nested-режиме).
|
||||
- В индексе: ссылка на родителя, список подпапок, список статей с полными заголовками (H1).
|
||||
- Исходный `INDEX.md` папки **не** дублируется как отдельная статья в списке — его тело (без ведущего H1) вшивается в автоиндекс.
|
||||
- В обычных статьях добавляется блок «вернуться в индекс папки».
|
||||
- В `Home.md` / `_Sidebar.md` вставляется/обновляется блок между маркерами `export_docs:begin` / `export_docs:end`.
|
||||
- `_Sidebar`: дерево папок в порядке родителя → дети (DFS); подпись — только имя сегмента (`📁 mapping`), без слова «Папка» и без полного пути.
|
||||
|
||||
## Конвертация ссылок
|
||||
|
||||
Для Markdown-ссылок вида `[text](target)` и ``:
|
||||
|
||||
- внешние URL (`http(s)`, `mailto`, `ftp`), якоря `#...`, абсолютные `/...` — без изменений;
|
||||
- относительные ссылки на выгружаемые `.md` пересчитываются на новый относительный путь между целевыми файлами в wiki;
|
||||
- ссылки на невыгружаемые файлы остаются как есть.
|
||||
- относительные ссылки на выгружаемые `.md` пересчитываются на целевой путь в wiki; в Markdown-цели **суффикс `.md` опускается** (Gitea: `/wiki/page`, не `/wiki/page.md`);
|
||||
- цели URL-кодируются (пробелы, скобки, кириллица);
|
||||
- локальные ссылки на файлы вне выгрузки, но внутри git-репозитория источника, переписываются в `https://…/src/branch/<branch>/<relpath>`;
|
||||
- прочие локальные файлы, попавшие в выгрузку как вложения, копируются, ссылки пересчитываются.
|
||||
|
||||
Цель: сохранить ссылочность внутри набора опубликованных статей.
|
||||
Rewrite поддерживает inline и reference-style (`[id]: target`).
|
||||
|
||||
## Управление удалениями (без потери чужих wiki-страниц)
|
||||
|
||||
Используется отдельный manifest для `export_docs` в корне wiki clone:
|
||||
Manifest в корне wiki clone: `manifest.export_docs.<hash(folder)>.json`.
|
||||
|
||||
- `manifest.export_docs.<hash(folder)>.json`.
|
||||
|
||||
При следующем запуске для того же `--folder`:
|
||||
При следующем `push` для того же `--folder`:
|
||||
|
||||
- файлы из предыдущего manifest, которых нет в новой выгрузке, удаляются;
|
||||
- статьи/файлы, не управляемые этим manifest, не трогаются.
|
||||
|
||||
Перед `git add` снимаются флаги `assume-unchanged` / `skip-worktree` с `Home.md` и `_Sidebar.md` (иначе Gitea-клон может не закоммитить правки навигации).
|
||||
|
||||
## Ограничения текущей версии
|
||||
|
||||
- Автоматически обрабатываются только `.md` как источники выгрузки.
|
||||
- Вложения (картинки/файлы), на которые есть локальные ссылки в `[](...)` / ``, **копируются** в wiki вместе со статьями (с сохранением структуры каталогов относительно статического префикса маски).
|
||||
- Rewrite поддерживает как:
|
||||
- inline-ссылки/картинки: `[](...)` и ``;
|
||||
- reference-style определения: `[id]: target` (то есть ссылки вида `[text][id]` остаются рабочими, т.к. переопределения переписываются).
|
||||
- Источники выгрузки — только `.md`.
|
||||
- Вложения копируются только если на них есть локальная ссылка в выгружаемом Markdown.
|
||||
- Монтирование чужого дерева в подпапку wiki одной маской вида `ws:./ws-rhana/docs/**` пока не реализовано — используйте отдельные `--files` / `--folder` или ссылки на `src/branch/…`.
|
||||
|
||||
Reference in New Issue
Block a user