docs: опиши работу с сабмодулями и добавь сборку Doxygen

Doxyfile

@@ -0,0 +1,27 @@
+PROJECT_NAME           = "templates"
+PROJECT_BRIEF          = "Переносимые библиотеки и правила интеграции"
+OUTPUT_DIRECTORY       = .codex-build/doxygen
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = Russian
+INPUT                  = README.md NEW_PROJECT.md CONTRIBUTING.md doc/submodules.dox c python
+FILE_PATTERNS          = *.h *.c *.dox *.md
+RECURSIVE              = YES
+USE_MDFILE_AS_MAINPAGE = README.md
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+EXTRACT_ALL            = NO
+EXTRACT_STATIC         = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_FROM_PATH        = .
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+GENERATE_LATEX         = NO
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
+HAVE_DOT               = NO

NEW_PROJECT.md

@@ -120,3 +120,188 @@ USB gs_usb и конкретной разводки адаптера; перен
 
 Так новый проект не является копией старого: он использует общие ядра одной
 версии, а аппаратные отличия видны в одном небольшом каталоге `port/`.
+
+## Слияние и обновление `templates` как Git submodule
+
+### Что именно хранит основной проект
+
+Основной проект не хранит содержимое `lib/templates` в своей истории. Вместо
+этого он хранит **gitlink** — ссылку на один конкретный commit репозитория
+`templates`. Поэтому при работе есть два независимых уровня истории:
+
+1. изменения библиотек сливаются и публикуются в репозитории `templates`;
+2. основной проект отдельным коммитом переводит gitlink на проверенную ревизию
+   `templates`.
+
+Обычный `git merge` в основном проекте не переносит исходники между ветками
+`templates` и не создаёт merge-коммит внутри сабмодуля. Он может только выбрать
+одну из уже существующих ссылок на commit. Если ссылки разошлись, сначала нужно
+получить общий commit в самом `templates`, а затем зафиксировать его в основном
+проекте.
+
+Текущую зафиксированную ревизию удобно смотреть из корня основного проекта:
+
+```bash
+git submodule status lib/templates
+git diff --submodule=log
+```
+
+Символ `-` перед SHA в `git submodule status` означает, что сабмодуль ещё не
+инициализирован; `+` — что рабочая копия сабмодуля находится не на том commit,
+который записан в основном проекте; `U` — конфликт gitlink.
+
+### Клонирование проекта и переключение его веток
+
+Новый клон лучше сразу создавать вместе с сабмодулями:
+
+```bash
+git clone --recurse-submodules <url-основного-проекта>
+cd <основной-проект>
+```
+
+Если проект уже клонирован:
+
+```bash
+git submodule update --init --recursive
+```
+
+После `git switch`, `git checkout`, `git pull` или завершения слияния основной
+проект может начать ссылаться на другую ревизию `templates`. Рабочее дерево
+сабмодуля следует явно привести к записанному состоянию:
+
+```bash
+git submodule update --init --recursive
+```
+
+Это нормальный и воспроизводимый режим: внутри `lib/templates` обычно будет
+detached HEAD, потому что проект фиксирует commit, а не ветку. Не следует делать
+там `git pull`, пока не выбрана рабочая ветка и не понятно, какую ревизию должен
+получить основной проект.
+
+### Обычное обновление проекта на новую версию `templates`
+
+Сначала изменение должно быть проверено, закоммичено, отправлено и слито в
+целевую ветку самого репозитория `templates`. После этого из корня основного
+проекта выполняется:
+
+```bash
+git -C lib/templates fetch origin
+git -C lib/templates switch --detach origin/master
+git add lib/templates
+git diff --cached --submodule=log
+git commit -m "build(templates): обновить общие библиотеки"
+```
+
+Перед коммитом нужно собрать основной проект и прогнать его тесты: успешные
+тесты в `templates` подтверждают работу библиотеки, но не проверяют конкретный
+порт, настройки платы и интеграцию приложения.
+
+Коммит основного проекта содержит только переход со старого SHA сабмодуля на
+новый. Случайные незакоммиченные файлы внутри `lib/templates` в него не входят.
+Проверить оба уровня перед фиксацией можно так:
+
+```bash
+git status
+git -C lib/templates status
+git diff --submodule=log
+```
+
+Не нужно обновлять сабмодуль на последний `master` автоматически при каждой
+сборке. Зафиксированный SHA нужен именно для того, чтобы одна и та же версия
+проекта всегда собиралась с одной и той же версией библиотек.
+
+### Если библиотеку правят из рабочего дерева основного проекта
+
+Нельзя коммитить изменение, оставаясь на detached HEAD: такой commit легко
+потерять при следующем `git submodule update`. Сначала внутри сабмодуля создаётся
+обычная ветка:
+
+```bash
+git -C lib/templates fetch origin
+git -C lib/templates switch -c feat/<имя> origin/master
+```
+
+Затем изменения коммитятся и отправляются именно в репозиторий `templates`:
+
+```bash
+git -C lib/templates add <файлы>
+git -C lib/templates commit -m "feat(<библиотека>): <описание>"
+git -C lib/templates push -u origin feat/<имя>
+```
+
+После проверки ветка сливается в `master` репозитория `templates`. Только после
+публикации итогового commit основной проект обновляет свой gitlink по процедуре
+из предыдущего раздела. Не следует отправлять в общий основной проект ссылку на
+commit сабмодуля, которого ещё нет на сервере: остальные разработчики и CI не
+смогут его получить.
+
+### Что происходит при слиянии веток основного проекта
+
+Возможны три ситуации:
+
+1. Gitlink изменён только в одной ветке. Git обычно принимает эту ревизию
+   автоматически. После merge нужно выполнить `git submodule update` и тесты.
+2. Обе ветки указывают на разные commits, но один commit `templates` является
+   предком другого. Следует выбрать более новый проверенный commit, выполнить
+   `git add lib/templates` и продолжить merge.
+3. Обе ветки указывают на расходящиеся commits `templates`. Это настоящий
+   конфликт истории сабмодуля: выбирать один SHA наугад нельзя, потому что так
+   потеряются изменения второй ветки.
+
+При конфликте сначала смотрят, какие ссылки пришли с обеих сторон:
+
+```bash
+git ls-files -u lib/templates
+git -C lib/templates fetch origin
+git -C lib/templates log --oneline --graph --decorate --all
+```
+
+Затем в отдельной ветке **репозитория `templates`** объединяют оба commit,
+устраняют конфликты исходников, запускают тесты и публикуют результат:
+
+```bash
+git -C lib/templates switch -c merge/<имя> <sha-одной-стороны>
+git -C lib/templates merge <sha-другой-стороны>
+# исправить конфликты и запустить тесты templates
+git -C lib/templates add <исправленные-файлы>
+git -C lib/templates commit
+git -C lib/templates push -u origin merge/<имя>
+```
+
+Если общий merge-коммит уже существует в `origin/master`, создавать ещё один не
+нужно: достаточно выбрать существующий SHA. После получения итогового commit
+конфликт завершается на уровне основного проекта:
+
+```bash
+git -C lib/templates switch --detach <итоговый-sha>
+git add lib/templates
+git diff --cached --submodule=log
+git merge --continue
+git submodule update --init --recursive
+```
+
+`git add lib/templates` здесь отмечает разрешённым именно gitlink. Не нужно
+удалять каталог, копировать библиотеку поверх него или разрешать конфликт как
+обычный текстовый файл.
+
+### Что должно попасть в merge request основного проекта
+
+Перед отправкой результата следует проверить:
+
+1. итоговый commit `templates` доступен в удалённом репозитории;
+2. `git -C lib/templates status` не показывает локальных изменений;
+3. `git submodule status` не начинается с `+`, `-` или `U`;
+4. `git diff --submodule=log <целевая-ветка>...HEAD` показывает ожидаемый набор
+   commits библиотек;
+5. тесты `templates`, сборка основного проекта и проверки на целевой плате
+   прошли;
+6. в основном проекте закоммичены необходимые изменения адаптеров, конфигурации
+   и сам новый gitlink.
+
+После получения ветки другой разработчик восстанавливает ровно выбранное
+состояние одной командой:
+
+```bash
+git pull
+git submodule update --init --recursive
+```

README.md

@@ -69,6 +69,11 @@ templates/
 В ней отдельно описаны граница ядра, ABI, память, три wire format и состояние
 портов Windows, Android, Linux и MCU.
 
+Обзор всего репозитория, включая слияние при подключении через submodule:
+[`doc/index.html`](doc/index.html). Справочник Doxygen собирается командой
+`powershell -ExecutionPolicy Bypass -File doc/build-doxygen.ps1` в
+`.codex-build/doxygen/html/index.html`.
+
 ## Как подключить к проекту
 
 **Сабмодуль** — когда нужна одна конкретная версия и обновление по команде:
@@ -78,6 +83,10 @@ git submodule add https://git.rd12.ru/Andrey/templates.git lib/templates
 git submodule update --init --recursive
 ```
 
+Как обновлять зафиксированную ревизию, переносить изменения из проекта и
+разрешать конфликт gitlink при слиянии веток, подробно описано в разделе
+[`Слияние и обновление templates как Git submodule`](NEW_PROJECT.md#слияние-и-обновление-templates-как-git-submodule).
+
 Дальше в сборку добавляются только нужные каталоги:
 
 ```

doc/build-doxygen.ps1

@@ -0,0 +1,28 @@
+[CmdletBinding()]
+param()
+
+$ErrorActionPreference = 'Stop'
+$repositoryRoot = Split-Path -Parent $PSScriptRoot
+$doxygen = Get-Command doxygen -ErrorAction SilentlyContinue
+
+if (-not $doxygen) {
+    throw 'Doxygen не найден в PATH. Установите Doxygen и повторите запуск.'
+}
+
+Push-Location $repositoryRoot
+try {
+    & $doxygen.Source Doxyfile
+    if ($LASTEXITCODE -ne 0) {
+        throw "Doxygen завершился с кодом $LASTEXITCODE."
+    }
+}
+finally {
+    Pop-Location
+}
+
+$indexPath = Join-Path $repositoryRoot '.codex-build\doxygen\html\index.html'
+if (-not (Test-Path -LiteralPath $indexPath)) {
+    throw "Doxygen не создал ожидаемый файл: $indexPath"
+}
+
+Write-Host "[DONE] Doxygen HTML: $indexPath"

doc/submodules.dox

@@ -0,0 +1,96 @@
+/**
+@page submodule_workflow Слияние templates как Git submodule
+
+Основной проект хранит не файлы `templates`, а gitlink: ссылку на один точный
+commit отдельного репозитория. Поэтому слияние выполняется на двух уровнях:
+
+1. исходники и их конфликты объединяются в репозитории `templates`;
+2. основной проект отдельным commit фиксирует итоговый SHA сабмодуля.
+
+@section submodule_clone Клонирование и переключение веток
+
+Новый проект клонируется вместе с сабмодулями:
+
+@code{.sh}
+git clone --recurse-submodules <url-основного-проекта>
+@endcode
+
+После `git switch`, `git pull` или merge рабочее дерево приводится к gitlink,
+который записан в выбранной ревизии проекта:
+
+@code{.sh}
+git submodule update --init --recursive
+@endcode
+
+Detached HEAD внутри `lib/templates` в этом режиме является нормой: основной
+проект фиксирует commit, а не плавающую ветку.
+
+@section submodule_update Обновление зафиксированной версии
+
+Изменение сначала должно быть проверено и слито в `master` репозитория
+`templates`. Затем основной проект выбирает опубликованный commit:
+
+@code{.sh}
+git -C lib/templates fetch origin
+git -C lib/templates switch --detach origin/master
+git add lib/templates
+git diff --cached --submodule=log
+git commit -m "build(templates): обновить общие библиотеки"
+@endcode
+
+Перед commit проверяются тесты самой библиотеки, сборка проекта, адаптеры,
+конфигурация платы и аппаратные тесты. Автоматически двигать сабмодуль на
+последний `master` при каждой сборке не следует: это уничтожает
+воспроизводимость.
+
+@section submodule_develop Изменение templates из основного проекта
+
+Перед редактированием нужно выйти из detached HEAD в обычную ветку:
+
+@code{.sh}
+git -C lib/templates fetch origin
+git -C lib/templates switch -c feat/<имя> origin/master
+@endcode
+
+Commit и ветка отправляются в удалённый репозиторий `templates`. Основной
+проект обновляет gitlink только после публикации итогового SHA, иначе коллеги
+и CI не смогут получить указанную ревизию.
+
+@section submodule_conflict Разрешение конфликта gitlink
+
+Если ветки основного проекта указывают на расходящиеся commits сабмодуля,
+выбирать `ours` или `theirs` наугад нельзя. Сначала определяются обе ссылки:
+
+@code{.sh}
+git ls-files -u lib/templates
+git -C lib/templates fetch origin
+git -C lib/templates log --oneline --graph --decorate --all
+@endcode
+
+Оба commit объединяются и тестируются в отдельной ветке репозитория
+`templates`. После публикации общего commit конфликт завершается в основном
+проекте:
+
+@code{.sh}
+git -C lib/templates switch --detach <итоговый-sha>
+git add lib/templates
+git diff --cached --submodule=log
+git merge --continue
+git submodule update --init --recursive
+@endcode
+
+`git add lib/templates` отмечает разрешённым gitlink. Удалять каталог или
+копировать в него файлы для разрешения конфликта не требуется.
+
+@section submodule_checklist Проверка перед merge request
+
+- итоговый commit `templates` опубликован;
+- `git -C lib/templates status` не показывает локальных изменений;
+- `git submodule status` не начинается с `+`, `-` или `U`;
+- `git diff --submodule=log` показывает ожидаемое обновление;
+- тесты библиотек, сборка основного проекта и проверка платы прошли;
+- изменения адаптеров и новый gitlink закоммичены в основном проекте.
+
+Полная инструкция с разбором всех трёх вариантов merge находится в
+`NEW_PROJECT.md`.
+*/