docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+39
View File
@@ -0,0 +1,39 @@
# Внутренние справочники репозитория
Сайт покрывает «как пользоваться и как устроено». Для **глубокой правки кода**
в репозитории живут авторитетные справочники (`docs/agent/`, читаются наравне
с `AGENTS.md`) и закоммиченные спецификации форматов (`docs/standards/`).
В этот сайт они не включены (огромные тексты спецификаций) — ссылки ведут на Gitea.
## Справочники `docs/agent/`
|Документ|Читать при|
|---|---|
|[pipeline.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/pipeline.md)|правке конвейера `WordPdfConverter`, нормализаторов, валидатора; шаги 0–7 с обоснованиями, правила 1–12|
|[doc-bridge.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md)|правке моста `internal/doc`; классы ↔ секции [MS-DOC]/[MS-CFB], остаток моста|
|[chart.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md)|правке `internal/chart`; пейнтеры, калибровки по Word, защитные лимиты, §ECMA-376|
|[render-limitations.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md)|любой попытке «починить» расхождение с Word — сначала стоп-лист|
|[testing.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/testing.md)|добавлении/правке тестов; счётчики, пиксельные допуски, фикстуры, конвенции|
|[ci-cd.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md)|правке workflow'ов, Containerfile'ов, деплоя|
|[repo-map.md](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)|поиске «где живёт X»: полная карта каталогов/файлов, REST-карта, конвенции|
## Спецификации `docs/standards/`
Нормативные тексты форматов, закоммиченные в репозиторий
(навигатор — `docs/standards/README.md`, ссылка в коде — с номером секции):
|Каталог|Содержимое|
|---|---|
|`ooxml/`|ECMA-376 Part 1 (PDF + md), [MS-OI29500], [MS-ODRAWXML], полные наборы XSD strict/transitional|
|`binary/`|[MS-CFB], [MS-OSHARED], [MS-ODRAW], [MS-OLEPS], [MS-OFFCRYPTO], [MS-OVBA], [MS-WMF], [MS-EMF]|
|`doc/`|[MS-DOC] — бинарный формат Word 97–2003|
|`docx/`|XSD-валидация фикстур (`validate-fixtures.py`)|
## Корневые документы
- [`AGENTS.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/AGENTS.md) —
правила репозитория: конвейер, инварианты, команды, конвенции, гейты.
- [`README.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/README.md) —
короткая точка входа в проект.
- [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md) —
все Secrets/Variables CI и настройка branch protection.