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:
@@ -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.
|
||||
Reference in New Issue
Block a user