Всем привет!

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

Введение

Очередной проект требует документации. У нас в разработке присутствует пара видов документации TypeDoc & JSDoc. Конечный вариант нашей документации является директорией HTML файлов, которые сгенерированы инструментом документации. Знаете, мне как разработчику было бы здорово запускать документацию на стороннем сервере. Сторонний сервер есть ни что иное как наш старый добрый Docker контейнер. Запуск Docker контейнера является ни чем иным, как управлением Unix системой через командную строку, CLI.

С чем мы сталкиваемся на каждом шаге управления документацией проекта? Инструменты генерирования документации, CLI. Как бы ни было мало сказано, оба названных направления предоставляют огромный спектр инструментов и методологий информатики. Давайте сегодня не останавливаться на инструментах, а попробуем погрузиться в Command-line Interface.

CLI

Так что же из себя представляет CLI и при чем здесь автоматизация? CLI представляет из себя текстовый интерфейс между человеком и Unix системой, где инструкции передаются посредством команд, текстовых строк. Команда представляет из себя название команды и ее параметры. Типизация Unix команд отсутствует, но общий подход их использования регламентирован.

Итак, давайте рассмотрим процесс создания документации проекта. Наш проект состоит как из JavaScript, так и TypeScript кода. При помощи JSDoc & TypeDoc мы можем автоматизировать процесс создания кодовой документации проекта. Для генерирования документации необходимы следующие команды:

• TypeDoc
  
  

  typedoc --out .docs/ts/html --readme ./docs/README.md ./src

• JSDoc
  
  

  jsdoc ./ -d ./.docs/js/html -R ./docs/README.md

Автоматизация данного действия поддерживается npm-scripts.

Созданная документация является ничем иным, как набором HTML файлов. Как и сказано выше, давайте создадим наш отдельный сервер для запуска нашей документации. Для запуска сервера будем использовать стандартные инструменты: Docker, Docker Compose. Предлагаю разобрать код.

#!/usr/bin/env node

/*
 * Raman Marozau <engineer.morozov@gmail.com>, 2019-present
 */

const {
  execAction,
  stop,
  Logger,
  EMPTY_LINE,
  ANSI_FG_GREEN,
  ANSI_FG_NC,
} = require('@softeq/utils');

const { exec, execSync } = require('child_process');
const fs = require('fs');

const DOCKER_COMPOSE_FILE_PATH = `${__dirname}/../docs.docker-compose.yml`;
const DOCKER_COMPOSE_FILE_PATH_DEFAULT = `${__dirname}/../docker-compose.yml`;
const DOCKER_CONTAINER_NAME = 'docs.nginx';
const DOCKER_SERVER_PORT = 7837;

if (!fs.existsSync(DOCKER_COMPOSE_FILE_PATH)) {
  Logger.error(`${DOCKER_COMPOSE_FILE_PATH} DOES NOT exist.${EMPTY_LINE}`);
}

exec(`docker stop ${DOCKER_CONTAINER_NAME} && docker rm ${DOCKER_CONTAINER_NAME}`, execAction((_, __, err) => {
  if (err && !err.message.includes(`No such container: ${DOCKER_CONTAINER_NAME}`)) {
    Logger.error(err);
  }
  execSync(`docker-compose --file ${DOCKER_COMPOSE_FILE_PATH_DEFAULT} --file ${DOCKER_COMPOSE_FILE_PATH} up --build -d`);
  Logger.stack([[`${ANSI_FG_GREEN}%s${ANSI_FG_NC}`, `${EMPTY_LINE}Documentation server: http://localhost:${DOCKER_SERVER_PORT}${EMPTY_LINE}`]]);
}, { error: false, stderr: false }));

Для построения начального шага автоматизации процесса создания сервера документации используются Node.js утилиты работы с CLI.

Заключение

Итак, понятно как он работает. Видна одна проблема разработки. Наши действия представляют какие-либо инструменты разработки, но CLI представляет из себя лишь текстовую информацию. Мне как разработчику было бы приятно работать не с текстовой информацией, а с переменными, объектами, классами и подобное. Также стоит заметить, что создание сервера предоставляет древовидную иерархию команд. Давайте постараемся разобраться в двух пунктах выше.
На время остановимся.

> En