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
+64
View File
@@ -0,0 +1,64 @@
# Как контрибьютить
## Ветка и PR
Репозиторий: `git.pjandro.ru:pjandro/java-word-pdf`. Защищённые ветки — `main`,
`master`, `dev`: прямо в них не коммитим.
1. Ветка от свежей `main` (`git switch -c <name>`).
2. Коммиты логическими блоками.
3. Перед push — полный гейт: `./mise.sh run verify`.
4. `git push -u origin <name>` → pull request в дефолтную ветку.
5. CI на PR: `java` (единственный `mvn clean verify` в контейнере без fontconfig +
сводка покрытия комментарием) и `web` (`npm ci`, build, lint) — оба required.
`macos-sim` — не required.
## Конвенции кода
- Классы `final`, приватный конструктор, только `static` (stateless, DI в ядре нет);
в `internal/**` — package-private, `public` только вызываемым извне пакета.
- Ошибки публичного API — только `ConversionException` (и подтипы); в chart —
деградация вместо падения.
- Javadoc на русском: «зачем» + ссылка на секцию спецификации (§17.3.2.24,
[MS-DOC] §2.6.1…) + что сломается без шага + регрессия в формате
`Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx` (по этой строке
грепом восстанавливаются пары тестов).
- Модели — `record`; константы UPPER_SNAKE с javadoc-обоснованием числа.
- PMD-подавления (`@SuppressWarnings("PMD…")`, `// NOPMD`) запрещены.
- Логирование: `java.util.logging` — корневой пакет и `internal/`; SLF4J —
`internal/chart` и `wordpdf-app`; остальное молчит.
## Регрессивная конвенция (фикс бага)
Каждый фикс расхождения с Word оформляется полным набором:
```
нормализатор/рендерер → юнит на правило → тест во всём конвейере
→ javadoc-ссылка «Регрессия — Тест#имя, фикстура …»
```
Фикстуры для новых тестов не генерируются на лету и не перезаписываются:
`charts-smartart.docx` и `ole-embedded.docx` сделаны руками и **не перезаписываются
никогда**; все 12 `.doc` — эталоны заказчика.
## Критические инварианты (нарушение = битый вывод)
Прежде чем править ядро — прогнать глазами список (полный — `AGENTS.md`,
[repo-map](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/repo-map.md)):
- static-блок `WordPdfConverter` (sysprops `gsubFeatures=false`, отключение
сканов PhysicalFonts) — не удалять;
- `DrawingPreRenderer` обязан идти **до** `FOSettings`, иначе FOP молча теряет диаграммы;
- порядок нормализаторов правил 1–11 фиксирован;
- вендорный `docx2fo.xslt` — единственный XSL-стилист, дрейф-гейт
`vendoredXsltTracksJarCopy`;
- `slf4j-simple` обязателен в ядре;
- префикс `/word/media/chart-*` — контракт с `ChartImageHandler`;
- финальный `finally`-блок: temp-шрифты, кеши картинок, возврат реестра к бандлу.
## Документация сайта
Разделы сайта живут в `docs/` (кроме `docs/agent/`, `docs/standards/` — они не входят
в сайт). Правка/новая страница: обязательна запись в `nav` `mkdocs.yml` (иначе
strict-сборка падает). Проверка: `./mise.sh run docs-build`. Публикация —
[`docs-deploy`](../operations/docs-site.md).