Документация¶

Сайт собирается из трёх источников, и два из них — сам код.

src/**/*.php (код + PHPDoc) ──► phpDocumentor + saggre/phpdocumentor-markdown ──► docs/api/*.md ─┐
examples/**/*.php (исполняемые примеры, их запускает ExamplesTest) ──► вставляются в страницы ───┤
docs/tutorial, how-to, reference, explanation, errors (пишутся руками) ─────────────────────────────┤
                                                                                                 ▼
                                                                    Zensical ──► GitHub Pages

Генератор сайта — Zensical от авторов Material for MkDocs. Конфиг — обычный mkdocs.yml. Почему не MkDocs: ветка 1.x больше не развивается, а MkDocs 2.0 несовместим с темами и плагинами 1.x и не поддерживает нужные нам расширения Markdown. Если с Zensical что-то пойдёт не так, тот же mkdocs.yml собирается MkDocs 1.6 + Material 9.7 без изменений.

Структура: Diátaxis¶

Страницы разложены по четырём разделам Diátaxis — по тому, зачем читатель пришёл. Новая страница сначала получает раздел, потом текст. Если страница просится в два раздела сразу, это две страницы.

Раздел	Папка	Читатель хочет	Как писать
Обучение	`docs/tutorial/`	впервые получить работающий результат	шаги, каждый с видимым результатом; без отступлений и вариантов
Рецепты	`docs/how-to/`	решить конкретную задачу	заголовок — задача глаголом («Настроить лог»); от проблемы к решению
Справочник	`docs/reference/`, `docs/errors/`	точно проверить факт	таблицы, полнота, без уговоров и истории
Как это устроено	`docs/explanation/`	понять, почему так	решение, причина, цена; без инструкций

Тон — прямой и спокойный. Начинаем с проблемы читателя, а не с возможностей библиотеки. Без маркетинга и громких обещаний: что делает, чего не делает, чем за это платим. Обращаемся на «вы».

Команды¶

make docs-install   # один раз: Python-окружение в var/venv
make docs           # справочник API + сборка сайта в site/ (--strict: битые ссылки валят сборку)
make docs-serve     # локальный сервер с автообновлением: http://127.0.0.1:8000

PHPDoc: справочник API¶

Справочник docs/api/ генерируется на каждую сборку, в git его нет. Всё, что в нём написано, берётся из докблоков публичных классов и методов.

Первая строка докблока — краткое описание, она попадает в таблицы справочника.
Ниже — подробное описание в Markdown.
Пример использования — обычный блок кода ```php внутри докблока. Тег @example не используем: в phpDocumentor он ссылается на файл, а не на код в комментарии.
Типы пишем максимально точно (non-empty-string, list<Route>, class-string<ListenerInterface>): они попадают в справочник и проверяются Psalm.

Исполняемые примеры¶

Пример в руководстве — это файл в examples/ (в корне репозитория, не в docs/: иначе он попал бы на сайт как статический файл). Тест tests/Docs/ExamplesTest.php запускает каждый файл отдельным процессом PHP:

пример должен завершиться с кодом 0;
если рядом лежит файл .out с тем же именем, вывод примера должен с ним совпасть.

На страницу вставляется только нужная часть файла, между маркерами:

<?php

require __DIR__ . '/../../vendor/autoload.php';   // на странице этого не будет

// ...код, который увидит читатель...

На странице вставка всегда внутри блока кода, иначе Markdown разберёт PHP как текст. Это проверяет tests/Docs/MarkdownSnippetsTest.php:

```php
--8<-- "getting-started/check-installation.php:example"
```

```text
--8<-- "getting-started/check-installation.out"
```

<?php во вставке не нужен: подсветка PHP включена и без него (startinline в mkdocs.yml).

Страницы ошибок¶

Для каждого исключения src/**/SomethingWrong.php нужна страница docs/errors/something-wrong.md: что произошло, почему, как исправить. Текст исключения содержит ссылку на неё через Documentation::errorUrl('something-wrong'). Без страницы ArchitectureTest не пройдёт.

Публикация¶

.github/workflows/docs.yml собирает сайт на каждый pull request и при push в main публикует его на GitHub Pages. В настройках репозитория один раз нужно выбрать Settings → Pages → Source: GitHub Actions.