Сайт документации платформы профкома

В данном репозитории находятся исходники документации, расположенной по адресу https://docs.profcomff.com.

Документация собирается с помощью платформы Diplodoc.

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

Документация собирается из файлов Markdown в сайт, попутно используя переменные и конвертеры форматов. Чтобы убедиться что для выкатки документации возможно выполнить все необходимые скрипты, нужно его собрать в готовый сайт.

Необходимые инструменты:

• Node.js – скачивается и устанавливается тут https://nodejs.org/en
• yfm – Yandex Flavored Markdown, утилита node.js для конвертации документации в вебсайт. Устанавливается командой npm i @diplodoc/cli -g в командной строке Windows или терминале Linux/MacOS.

Сборка производится командой yfm -i ./docs -o ./dist из корня проекта. Результат сборки появится в папке ./dist.

Для проверки генерации документации из OpenAPI, запустите скрипт scripts/download_apis.sh в терминале Linux/MacOS или scripts/download_apis.bat в командной строке Windows. Этот скрипт скачивает последнии версии документации к API. Запустить полную сборку проекта возможно командой make build.

Сборка проекта автоматически производится при создании Pull Request в ветку main.

Локальный запуск

Запуск через Docker

Запустите команду docker compose up, сервис соберется и поднимется

Результат будет находится по адресу: http://localhost:8080, через минуту-две после ввода команды

Если сервис поднялся, в логах должно быть такое:

docs-diplodoc-1  | Available on:
docs-diplodoc-1  |   http://127.0.0.1:8080
docs-diplodoc-1  |   http://172.20.0.2:8080

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

• http-server – утилита node.js для локального запуска вебсайта. Устанавливается командой npm i http-server -g в командной строке Windows или терминале Linux/MacOS.

Для запуска требуется собранный проект в папку ./dist командой yfm -i ./docs -o ./dist (см. раздел "Сборка проекта").

Запуск вебсервера производится командой http-server ./dist -o из корня проекта. После выполнения команды откроется окно веб-браузера с локальной версией документации. Запустить полную сборку проекта и его локлаьный запуск возможно командой make run.