Как устроена документация NextPDF

Кратко

Руководство NextPDF следует фиксированному контракту: у каждой страницы одна тема, один режим Diataxis и один тип страницы. Для каждого типа страницы задан обязательный набор заголовков второго уровня. Небольшой набор манифестов и проверок помогает сохранять согласованность структуры по мере роста руководства.

На этой странице описана эта система, чтобы вы могли правильно разместить свой вклад. Полный нормативный контракт, включая точные списки заголовков, правила цитирования и процедуру подключения проверок, содержится во внутреннем управляющем документе docs/style/expansion-standard.md. Сначала прочитайте эту страницу. К тому документу обращайтесь при подготовке материалов.

Выбор типа страницы

Применяйте эти правила последовательно, чтобы решить, добавить новую страницу или расширить существующую:

Если материал представляет собой отдельную тему, которую читатель не ожидал бы увидеть на существующей странице, добавьте новую страницу.
Если материал дополняет тему, уже закреплённую за существующей страницей, расширьте эту страницу.
Если материал содержит детали, которые перегрузили бы страницу установки, быстрого старта или задачи, вынесите его на отдельную страницу и добавьте ссылку на неё.
В остальных случаях расширьте существующую страницу.

Когда вы определили, что страница нужна, задайте её режим Diataxis. Режим определяет тип страницы:

Tutorial обучает читателя, который осваивает материал. Используйте руководство по задаче, написанное в формате рецепта.
How-to помогает подготовленному читателю выполнить задачу. Используйте руководство по задаче, руководство по серверному API или руководство по комплекту средств разработки.
Reference фиксирует точные факты. Используйте справочник API или страницу-указатель.
Explanation помогает сформировать понимание. Используйте руководство для разработчиков или руководство по премиум-возможности.

Простой язык — это базовое требование для каждого режима, а не отдельный режим.

Каталог типов страниц

Контракт руководства определяет следующие типы. Повторно используйте существующий тип каждый раз, когда ваша страница содержит таблицу API. Вводите новый тип, существующий только как метка, только для страницы без таблицы API.

Типы страниц-указателей: section-index, api-index, extension-index.
Тип справочника: api-reference. Используйте его повторно для любой страницы со стандартной таблицей API, включая справочники по серверу и по Python SDK.
Тип пояснения: developer-guide. Используйте его повторно для текстов об архитектуре, жизненном цикле и точках расширения, включая руководства по серверу и по Python SDK.
Новые типы, которые существуют только как метки: premium-feature-guide и task-guide — оба для страниц без таблицы API.

Каждая страница начинается с ## At a glance. Каждая страница api-reference включает общую таблицу API и заголовок Development notes. Обязательные заголовки — это заголовки второго уровня, каждый на отдельной строке. Под ними можно добавлять дополнительные заголовки.

Контрольный список для авторов

При написании страницы выполняйте оба контрольных списка. Во внутреннем стандарте каждый пункт сформулирован как требование и снабжён ссылкой на соответствующий стандарт.

Удобство для разработчиков:

Берите запускаемые примеры из examples/ или tests/Cookbook и задавайте каждому ограждённому блоку кода информационную строку title=.
Указывайте предварительные требования во front-matter и во вступлении.
Показывайте ожидаемый вывод для любого примера, который его формирует.
Делайте блоки готовыми к копированию и вставке: один язык на блок, полные имена при первом употреблении и без завершающих символов приглашения.
Показывайте код, безопасный по умолчанию: рабочие примеры используют try/catch с наиболее конкретным исключением NextPDF и никогда не оставляют блок catch пустым.
Завершайте страницу ссылками на дальнейшие материалы и задавайте во front-matter related:.

Готовность к переводу:

Излагайте одну мысль в одном предложении, чтобы машинный перевод был предсказуемым.
Делайте заголовки и подписи короткими, поскольку большинство целевых языков удлиняют текст.
Избегайте идиом.
Сохраняйте имена символов, ключи конфигурации, флаги CLI и имена исключений в виде кода; названия стандартов, такие как PDF/A-4, PAdES и eIDAS, никогда не переводятся.
Задавайте i18n_ready и xliff_segments честно и используйте нормализацию Unicode NFC.

В вопросах стиля изложения, оформления примеров кода, терминологии и цитирования следуйте утверждённому листу переопределений стиля, на который ссылается внутренний стандарт.

Подключение проверок

Подключайте новую страницу с помощью этой упорядоченной процедуры:

Создайте каркас страницы так, чтобы её front-matter соответствовал схеме сайта.
Напишите основной текст в соответствии с обязательными заголовками для данного типа страницы.
Добавьте запись { path, owner, kind, headings[] } в docs/manual-contract.json. Путь указывается относительно src/content/docs, использует прямые слеши и не содержит ведущего слеша и ...
Для справочника API добавьте символы страницы в docs/api-coverage-manifest.json; каждый символ должен присутствовать на странице и существовать в исходном коде.
Обновляйте docs/source-manifest.json только в том случае, если страница берётся из нового исходного репозитория.
Добавьте страницу в нужную группу боковой панели в astro.config.mjs как явную запись.
Для англоязычной страницы добавьте строку покрытия локалей со всеми семнадцатью ячейками локалей в значении missing.
Запустите проверки документации, сборку и проверку бюджета производительности.

Страницы, принадлежащие сайту, находятся в src/content/docs, имеют owner со значением nextpdf-docs и никогда не содержат маркер агрегации. Агрегированные страницы берутся из исходного репозитория. Флаг публикации для них находится во front-matter источника, поэтому редактируйте их там, а не здесь.

Смотрите также

Интеграции: самый крупный проработанный пример структуры руководства, охватывающей несколько пакетов.
Внутренний управляющий документ docs/style/expansion-standard.md содержит полный контракт: точные списки заголовков для каждого типа страницы, правила цитирования и полную процедуру подключения проверок.