Как быстро и удобно документировать Angular проект с помощью модуля AddOnDoc из TaigaUI

[Kate]

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

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

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

• гайдлайн, стили, правила и рекомендации;
• 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
],

Используем документацию в компоненте
<tui-doc-page header='Money' path='npm' package ='cdk'>
<div class='page'>
Money &nbsp;&mdash; компонент для форматирования числа в input.
</div>
<tui-doc-example id='base' heading='Simple money' [description]='description' [content]='example1' >
<div>
<fo-money
[(ngModel)]='periodSum'
[allowNull]='true'
[onBlur]='true'
showingMaxFractionDigits='1.0-0'
editorMaxFractionDigits='1.0-0'
placeholder='Платеж'
></fo-money>
</div>
</tui-doc-example>
</tui-doc-page>
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

Заключение​

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


Источник статьи: https://habr.com/ru/company/europlan/blog/559804/