Правила документации¶
F-Layer использует шаблон документации Fuzzy Technologies: MkDocs Material, mkdocstrings-python и Griffe со статическим обнаружением из установленного wheel. Тема расширяется отслеживаемыми конфигурацией, CSS и SVG. Созданный HTML остаётся временным и неотслеживаемым.
Обнаружение API¶
Каждый модуль Python установленного пакета flayer, не являющийся частным, получает страницу API; flayer.__main__ — явно поддерживаемое исключение из правила путей с подчёркиванием. Частные модули и вспомогательные функции доступны только в исходниках, с указанием причин. Обнаружение читает синтаксис и не импортирует исполняемый код. Защита импорта прерывает сборку при попытке выполнения пакета. Весь установленный пакет должен совпадать с инвентарём и байтами исходников, кроме байткода. Публичные определения и вызываемые протоколы требуют точных якорей HTML; каждая страница API связывается с соответствующим исходником develop.
Каждый отслеживаемый файл соответствует ровно одному явному правилу покрытия. Все канонические Markdown-файлы, включая политики, правила выпуска, ADR, шаблоны и точки входа репозитория, отображаются и должны быть достижимы из английской начальной страницы. Тесты, инструменты, workflow, примеры, ресурсы и конфигурация имеют объяснённое назначение, а не выдуманную документацию API. Локализованные наложения отображаются обёрткой с явным состоянием проверки. Контракт покрытия определяет границу и машиночитаемые свидетельства.
Каждая отслеживаемая Markdown-таблица выровнена по содержимому столбцов. Проверка исходников проверяет читаемость до публикации; она сохраняет экранированные вертикальные черты, ячейки с кодом, маркеры выравнивания и буквальные примеры в блоках кода.
Английские авторские страницы используют отслеживаемый реестр единиц локализации. Созданные единицы API используют временный инвентарь с теми же устойчивыми ID символов и версионными хешами источника. Состояние их переводов явно равно missing; инвентарь не создаёт переводов или проверок.
Язык и проверка¶
Английский язык канонический. По запросу владельца проекта АИна сверила русские и китайские авторские страницы с английскими источниками. Проверенные страницы открываются сразу, без плашки черновика. Для отсутствующих или устаревших переводов показывается актуальный английский текст с соответствующим уведомлением. Страницы API и непереведённая инженерная документация остаются на английском.
Каждый перевод записывает устойчивый ID, хеш английского источника и путь. Одобрение требует редакционной и технической проверок с именем проверяющего, временем UTC и текущим хешем источника. F-Layer явно допускает проверки ИИ по ADR 0015. Такие записи отмечают проверяющего как ИИ и дополнительно фиксируют хеш проверенного перевода; они не означают проверку человеком. Изменение любого текста требует новой проверки. Обновление английского реестра само по себе не восстанавливает одобрение.
Терминология хранится в согласованных глоссариях. История проверок доступна в отслеживаемом реестре и свидетельствах сборки.
Публикация¶
Pull request и develop создают скачиваемые артефакты предпросмотра и свидетельств. Только событие push ветки master может развернуть проверенный артефакт Pages. Публикация документации отделена от публикации пакета.
Публичные маршруты: /F-Layer/en/, /F-Layer/ru/, /F-Layer/zh-CN/. Корневой адрес открывает английский справочник. Неизменяемая документация выпуска не заявляется до стабильного релиза.
ADR 0004 фиксирует генератор, проверку, хеши источника, fallback и границы публикации.