Как быстро и удобно документировать Angular проект с помощью модуля AddOnDoc из TaigaUI28.05.2021 13:46

Привет! Меня зовут Александр. Я работаю над веб продуктами компании Европлан. У нас порядка 50 веб-разработчиков, более 30 стратегических проектов, постоянный процесс онбординга и подключение коллег из смежных команд, поэтому документация библиотеки компонентов помогает быстро адаптироваться.

В этой статье я расскажу про способы документации Angular проектов и покажу как это можно сделать с помощью AddOnDoc из TaigaUI. Как говорят сами создатели Александр Инкин и Роман Седов, это конструктор Lego. И действительно: в нём есть много полезных модулей, которые можно использовать в своём проекте. В этой статье мы рассмотрим модуль AddOnDoc.

255d16895ac99add17792719779f0256.png

Для чего мы документируем проекты

Обычно, когда я говорю о библиотеке компонентов, мне нравится начинать свой рассказ с дизайн-систем. Дизайн-системы — это то, что позволяет повысить скорость и качество продуктов. Обычно дизайн-система состоит из следующих компонентов:

  • гайдлайн, стили, правила и рекомендации;

  • UIKIT, представленный в figma/sketch/photoshop;

  • библиотека готовых компонентов в виде кода (angular, react и т.д.).

В нашей компании проработаны корпоративные стили и регламенты по визуальному оформлению всего, с чем может взаимодействовать пользователь. Дизайнер проектирует интерфейсы продуктов в Figma и передает макеты разработчику. Мы начинали разработку продуктов в команде из нескольких человек. Раньше было легко договориться. Все знали, какие компоненты/пайпы/директивы/сервисы у нас есть. Сейчас команда выросла до 20-ти человек, плюс на это накладывается подключение разработчиков из смежных команд, а также адаптация новых сотрудников, да и сам проект активно развивается. Хочется иметь удобный инструмент для документации библиотеки компонентов с интерактивным просмотром их поведения. Итого с помощью документации мы решаем следующие задачи:

  • обмен знаниями между разработчиками

  • быстрая адаптация новых сотрудников

  • упрощение процесса создания продукта

  • единообразие интерфейса

Что мы документировали

Обычно документация включает в себя следующие разделы:

  • типографика

  • палитра

  • иконки

  • сетка

  • Angular компоненты (директивы, пайпы, сервисы)

Мы добавили еще несколько пунктов:

  • State менеджеры

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

  • инструменты, которые пригодятся в разработке (расширения vscode, плагины для Chrome и т.д.)

Какие решения для документации существуют

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

Storybook — одно из самых популярных open-source решений для документации в мире фронтенда.

Плюсы:

  • поддерживает Angular, React, Vue, Svelte, Ember

  • большое сообщество

  • множество полезных плагинов

  • наглядная демонстрация компонентов

  • open-source

Минусы:

  • нет возможности документировать компоненты декларативно, нужно использовать, описание в коде с помощью своего API (Template, props, Template.bind ({}))

  • хочется другой дизайн интерфейса

bit.dev — платный инструмент для команд, код хранится в облаке.

Плюсы:

  • это полноценная платформа для шеринга компонентов между командами

  • своя инфраструктура для ci/cd, тестирования

  • хорошее демо компонентов

  • дополнительная функциональность для анализа компонентов (bundle-size, dependencies и т.д.)

Минусы:

  • платный

  • слабая техподдержка: после публикации компонента произошла ошибка, отвечали пару недель

AddOnDoc — open-source пакет для документации проекта.

Плюсы:

  • лаконично, удобно, легко стартануть

  • декларативно пишешь документацию компонентов, ничем не отличается от обычного Angular компонента

  • open-source

  • отечественный продукт, легко можно списаться с ребятами по идеям и предложениям

Что лежит в основе AddOnDoc

В основе подсветки кода лежит библиотека highlight.js. Преимущество этой библиотеки в том, что она автоматически определяет и подсвечивает 191 язык. У нее более 6 миллионов загрузок в неделю и 18 тысяч звездочек на github. Думаю, поэтому команда taiga ui выбрала ее.

Настройка проекта для документации

Angular workspace позволяет создавать два типа проектов. Первый вид — это обычное приложение, второй вид — это библиотека. Workspace может содержать несколько проектов. Для документации внутри workspace был создан отдельный проект. Он импортирует в себя кастомные компоненты, типографику и цвета из основного проекта. Для него настроен отдельный ci/cd в gitlub. Получилось удобно, мы не задеваем основной проект, документируем и развертываем приложение отдельно от него.

Подключение AddOnDoc

Для начала нужно поставить пакеты из taiga-ui

npm i @taiga-ui/{cdk,core,kit}
npm i @taiga-ui/addon-doc

Далее необходимо добавить конфигурацию в AppModule: 

{
        provide: HIGHLIGHT_OPTIONS,
        useValue: {
            coreLibraryLoader: () => import('highlight.js/lib/core'),
            lineNumbersLoader: () => import('highlightjs-line-numbers.js'),
            languages: {
                typescript: () => import('highlight.js/lib/languages/typescript'),
                scss: () => import('highlight.js/lib/languages/scss'),
                xml: () => import('highlight.js/lib/languages/xml'),
            },
        },
    },

Использование

Импортируем модули для документации

imports: [
    CommonModule,
    ...
    TuiDocExampleModule,
    TuiDocPageModule,
    TuiDocDocumentationModule,
    TuiDocCodeModule,
    TuiDocDemoModule
  ],

Используем документацию в компоненте


  

    Money  — компонент для форматирования числа в input.

tui-doc-page — компонент для страницы документации.

параметры компонента:

  • header — заголовок

  • package — название пакета

tui-doc-example — компонент для документации конкретного примера. Для интерактивного демо внутри него просто пишется компонент.

параметры:

  • content — состоит из свойства TypeScript и Html. В первое свойство добавляется пример подключения и использования компонента/модуля/сервиса, во второе текст шаблона html

  • heading — заголовок примера

  • description — описание примера

const example1Html = require('!!raw-loader!./examples/1/template.html').default as string;

@Component({
  selector: 'fo-money-demo',
  templateUrl: './money-demo.component.html',
  styleUrls: ['./money-demo.component.scss'],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class MoneyDemoComponent implements OnInit {
  periodSum = 32434;
  example1 = {
    TypeScript: `@NgModule({
      imports: [
        CommonModule,
        MoneyModule
      ],
      exports: [ResizabledemoComponent],
      declarations: [ResizabledemoComponent]
    })`,
    HTML: example1Html,
  };
  constructor() { }

  ngOnInit() {
  }

}

Пример работы AddOnDoc

Пример работы AddOnDoc Taiga UIПример работы AddOnDoc Taiga UI

Заключение

В результате мы получили удобную интерактивную документацию проекта. Спасибо команде taiga ui за отличный инструмент! Мы задокументировали типографику, палитру, иконки, сетку, компоненты, пайпы, директивы и сервисы. А также добавили туда общие вопросы, рекомендации по разработке приложения.

© Habrahabr.ru