Руководство автора

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

Обзор

  • Пишите материал в AsciiDoc.

  • Проверяйте локально (Vale — стиль, htmltest — ссылки, предпросмотр сборки).

  • Фиксируйте изменения и открывайте pull request.

  • CI формирует HTML / PDF / DOCX и запускает QA-проверки.

  • Мультиверсийный сайт по Git-тегам; для каждой версии доступны собственные загрузки в _downloads.

Структура проекта

docs/
├── en/                    # компонент для английской версии
│   ├── antora.yml         # метаданные компонента
│   └── modules/ROOT/      # основной модуль Antora
│       ├── pages/         # страницы AsciiDoc
│       ├── assets/        # статика
│       │   └── images/    # локальные изображения
│       └── attachments/   # файлы для скачивания (идут в _downloads)
└── ru/                    # компонент для русской версии
    ├── antora.yml
    └── modules/ROOT/
        ├── pages/
        ├── assets/
        │   └── images/
        └── attachments/

Каждый язык оформлен как отдельный компонент Antora; названия и версии могут отличаться.

Подготовка окружения

  1. Выполните Installation & Setup.

  2. Клонируйте репозиторий и установите пакеты Node.js:

    npm ci --no-audit --no-fund

  3. Проверьте цепочку инструментов первичной сборкой:

    make build-all

Режимы сборки

Локальный — по умолчанию. Собирается только текущая ветка HEAD или ветка, указанная в BUILD_REF.

make build-all
make build-all BUILD_REF=my-feature

Теги — мультиверсионная сборка по всем Git-тегам.

make build-all BUILD_SCOPE=tags

Переменные Make: BUILD_SCOPE = local или tags, BUILD_REF по умолчанию HEAD.

Артефакты и размещение

PDF

  • build/pdf/<locale>/<version>/adaptadocx-<locale>.pdf

  • копируется в site/<locale>/<version>/_downloads/adaptadocx-<locale>.pdf

DOCX

  • build/docx/<locale>/<version>/adaptadocx-<locale>.docx

  • копируется в site/<locale>/<version>/_downloads/adaptadocx-<locale>.docx

Ссылки PDF и DOCX в шапке указывают на _downloads текущей версии.

Ежедневный процесс

  1. Редактируйте файлы .adoc в соответствующем языковом компоненте.

  2. Просматривайте сайт локально:

    make build-html

  3. Проверяйте стиль и ссылки:

    make test

  4. Формируйте все форматы при необходимости пакета для ревью:

    make build-all

  5. Проверьте артефакты в build/ и загрузки в site/<locale>/<version>/_downloads.

Проверка перед коммитом

Запускайте три основные проверки:

vale docs/
make build-html
htmltest -c .htmltest.yml build/site

Процесс pull request

  1. Создайте ветку фичи:

    git checkout -b feat/short-description

  2. Внесите изменения и выполните локальную сборку:

    make build-all && make test

  3. Закоммитьте, запушьте и откройте PR.

CI прикрепляет к запуску vale.xml и htmltest.log.

Конвейеры CI

Release (теги)

  • триггер — пуш в тег;

  • сборка в Docker с BUILD_SCOPE=tags;

  • проверка htmltest и Vale;

  • загрузка собранного сайта и прод-деплой.

QA checks (pull request в main)

  • линт shell-скриптов, запуск Vale;

  • сборка и htmltest для текущей ветки.

Security audit (pull request в main, push в теги)

  • неблокирующие проверки: OSV-Scanner, Sandworm, поиск запрещённых паттернов;

  • краткая сводка публикуется в отчёте запуска.

Процесс перевода

  1. Напишите или обновите английскую страницу.

  2. Скопируйте файл в зеркальный путь docs/ru/ и переведите.

  3. Проверьте кросс-ссылки в обоих языках.

  4. Запустите make build-html и убедитесь, что поиск работает.

  5. Откройте pull request.

Инструментарий

Категория Инструменты / Файлы

Редактирование

Редактор с поддержкой AsciiDoc

Валидация

Vale, htmltest, Shellcheck

Сборка

Makefile, Dockerfile

Конфигурация

antora-playbook-en.yml, antora-playbook-ru.yml, antora-assembler.yml, .vale.ini, config/default-theme.yml

CI

.github/workflows/release.yml, .github/workflows/qa-checks.yml, .github/workflows/security-audit.yml

См. также