From a2c68fa5d502cf04891bc4241b32d4da42db99bf Mon Sep 17 00:00:00 2001 From: mihailkudravcev Date: Wed, 29 Jul 2026 13:48:37 +0300 Subject: [PATCH] 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 --- CHANGELOG.md | 5 +++ README.md | 20 +++++++----- SPEC_EXPORT_DOCS.md | 75 +++++++++++++++++++++++++++++---------------- 3 files changed, 66 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a135bb2..4c4cd8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index c682067..f32f411 100644 --- a/README.md +++ b/README.md @@ -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//…`. ```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`). Общие параметры источника (взаимоисключающие): diff --git a/SPEC_EXPORT_DOCS.md b/SPEC_EXPORT_DOCS.md index fc53435..52e8dec 100644 --- a/SPEC_EXPORT_DOCS.md +++ b/SPEC_EXPORT_DOCS.md @@ -5,73 +5,94 @@ Публикация аналитических Markdown-статей из рабочих каталогов проекта (`docs/` и др.) в wiki-репозиторий (`*.wiki.git`) с: - размещением в указанной папке wiki (`--folder`); -- сохранением структуры подкаталогов по маске; -- конвертацией локальных ссылок между выгружаемыми `.md`-файлами. +- сохранением логической структуры подкаталогов (по умолчанию — плоские имена файлов); +- конвертацией локальных ссылок между выгружаемыми `.md` и вложениями; +- автоиндексами папок и навигацией в `Home` / `_Sidebar`. ## CLI ```bash python export_docs.py push \ --files [ ...] \ - -s \ - --folder \ + [--folder ] \ + [-s | -c ] \ [--wiki-url ] [--remote origin] \ [--work-dir ] [-o ] [--branch main] \ + [-m "commit message"] [--dry-run] [--verbose] \ + [--no-flat-root] + +python export_docs.py clean \ + [--folder ] \ + [-s | -c ] \ + [--wiki-url ] [--remote origin] \ + [--work-dir ] [--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..json` и блок `` в `Home.md` / `_Sidebar.md`. Параметр `--files` не используется. ## Правила размещения файлов 1. Для каждой маски определяется статический префикс (часть до wildcard). 2. Для каждого совпавшего `.md` считается относительный путь от этого префикса. 3. В wiki файл размещается как: - - `/`. + - **flat (по умолчанию):** `____.md` (например `docs/transfer/a.md` → `docs__transfer__a.md`); + - **nested (`--no-flat-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)` и `![alt](target)`: - внешние URL (`http(s)`, `mailto`, `ftp`), якоря `#...`, абсолютные `/...` — без изменений; -- относительные ссылки на выгружаемые `.md` пересчитываются на новый относительный путь между целевыми файлами в wiki; -- ссылки на невыгружаемые файлы остаются как есть. +- относительные ссылки на выгружаемые `.md` пересчитываются на целевой путь в wiki; в Markdown-цели **суффикс `.md` опускается** (Gitea: `/wiki/page`, не `/wiki/page.md`); +- цели URL-кодируются (пробелы, скобки, кириллица); +- локальные ссылки на файлы вне выгрузки, но внутри git-репозитория источника, переписываются в `https://…/src/branch//`; +- прочие локальные файлы, попавшие в выгрузку как вложения, копируются, ссылки пересчитываются. -Цель: сохранить ссылочность внутри набора опубликованных статей. +Rewrite поддерживает inline и reference-style (`[id]: target`). ## Управление удалениями (без потери чужих wiki-страниц) -Используется отдельный manifest для `export_docs` в корне wiki clone: +Manifest в корне wiki clone: `manifest.export_docs..json`. -- `manifest.export_docs..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/…`.