Версия: 0.0.16
На главную

Написание документации

Этот раздел предназначен для разработчиков Payment Widget. Если вы просто используете его, то тут для вас ничего нет.

Документация представляет собой набор статических файлов, которые генерируются во время сборки. Скрипт сборки лежит в src/sdk/build/build-docs.mjs.

Все страницы документации находятся в src/sdk/docs/pages/. Каждый файл - отдельная страница. При сборке скрипт автоматически проходится по всем файлам и добавляет их на главную.

Название ссылки на главной - это заголовок # Заголовок либо название файла, если заголово не найден.

Можно создавать .html файлы, в этом случае template.html не применяется. Не забудьте добавить стили:

<link rel="stylesheet" href="/0-0-16/index.css" />
<link rel="stylesheet" href="/0-0-16/highlight.css" />

Переменные в шаблонах

Если нужно подставить какое-то значение, используйте плейсхолдер {{my_custom_value}}. После этого, добавьте значение по-умолчанию в src/sdk/build/pasteTemplateValues.mjs:

const VARIABLES = {
  head: '',
  body: '',
  index: '',
  typedefsContent: '',
  dockerfileContent: '',
  host: SDK_HOST,
  version: SDK_VERSION,
  my_custom_value: 'Some string',
};

Если значение нужно прокинуть динамически, добавьте нужный код в функцию renderPage в файле src/sdk/build/renderPage.mjs:

markdownContent = pasteTemplateValues(markdownContent, {
  typedefsContent,
  dockerfileContent,
  my_custom_value: getDynamicValue(),
});

Ещё один вариант - использовать JS. Пример можно увидеть в файле src/sdk/docs/pages/index.md:

<li><a href="deploy.html">Деплой</a></li><li><a href="docs-development.html">Написание документации</a></li><li><a href="getting-started.html">Использование</a></li><li><a href="sdk-development.html">Разработка SDK</a></li>

Обратите внимание на data-type="build" - это важно. Только скрипты с этим атрибутом выполнятся при сборке. Пути для импортов должны быть абсолютными.

В будущем, если потребуется, настроим что-то человеческое для сборки, какой-нибудь astro или ещё что. Сейчас по минимуму заполняем package.json виджета.

Тестирование

Выполните сборку:

npm run sdk:build:docs -- --host=http://127.0.0.1:3001

Обратите внимание на двойной дефис: “–”. Он обязателен при использовании npm.

В дальнейшем можно запускать только сборку документации:

npm run sdk:build:docs -- --host=http://127.0.0.1:3001 --skip-lib-build

Эта команда пропустит шаг со сборкой SDK.

Собранные файлы попадут в папку ./sdk-build/latest

Если нужно указать определённую версию добавьте аргумент --version=0.0.16:

npm run sdk:build:docs -- --host=http://127.0.0.1:3001 --version=1.0.1

В этом случае собранные файлы будут в папке ./sdk-build/1.0.1

Запустите сервер:

npm run sdk:serve -- -p 3001

Hot reload пока не поддерживается.

Для полноценного тестирования SDK, вместе с запуском самого виджета, смотрите раздел Разработка SDK

Устройство процесса сборки всех версий

Скрипт:

npm run sdk:build -- --host=https://dev-sdk.paybetget.cash

Выполняет сборку всех версий SDK и документации. Этот скрипт используется для деплоя.

Сборка идёт по следующим шагам:

Сначала текущие изменения помещаются в git stash - src/sdk/build/versioning/beforeStart.mjs
Создаётся временная ветка с префиксом + uuid v4 - src/sdk/build/versioning/beforeStart.mjs
После смотрим на список тэгов и достаём все с префиксом “sdk-version-” - src/sdk/build/versioning/getVersions.mjs
Для каждой версии возвращаем её номер и хэш коммита - src/sdk/build/versioning/getVersions.mjs
Проходимся по версиям, ресетимся на коммит версии, устанавливаем зависимости - src/sdk/build/versioning/buildVersion.mjs
Запускаем скрипты сборки - src/sdk/build/versioning/buildVersion.mjs
Парсятся аргументы командной строки - src/sdk/build/argv.mjs
Собирается список файлов в папке src/sdk/docs/pages - src/sdk/build/constants.mjs
Запускается скрипт сборки кода библиотеки - vite build --config src/sdk/build/vite.config.ts
После этого копируем стили библиотеки “highlight.js” для подсветки синтаксиса - src/sdk/build/build-docs.mjs
Загружаем html шаблон в который будут подставляться страницы и копируем index.css - src/sdk/build/build-docs.mjs
Идём по списку файлов в папке src/sdk/docs/pages и рендерим их - src/sdk/build/renderPage.mjs
Сохраняем результат - src/sdk/build/build-docs.mjs
Переключаемся обратно на текущую git-ветку, достаём stash и удаляем временную ветку в которой собирали версии - src/sdk/build/versioning/beforeStart.mjs

Скрипт подразумевает что папка с собранными версиями (./sdk-build) добавлена в .gitignore

Скрипты сборки написаны на js, чтобы не было необходимости в отдельном шаге сборки для скриптов сборки. Я не предполагаю множества изменений для них - скорее полную их замену на комплект vite + plugins.

Ограничения:

Приходится для каждой версии устанавливать ВСЕ зависимости, так как sdk не является отдельным пакетом. Но это компенсируется минимальными изменениями между версиями, поэтому в реальности просто уходит время на проверку npm что всё уже и так есть
Важно чтобы NODE_ENV НЕ была “production” на время установки зависимостей, иначе не установятся devDependencies и сборка сломается.
Относительные импорты js кода внутри .md и .html не всегда корректно работают. Приходится использовать абсолютные. Пример: src/sdk/docs/pages/index.md