[Angular] Как быстро и удобно документировать Angular проект с помощью модуля AddOnDoc из TaigaUI
Автор
Сообщение
news_bot ®
Стаж: 6 лет 3 месяца
Сообщений: 27286
Привет! Меня зовут Александр. Я работаю над веб продуктами компании Европлан. У нас порядка 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 — компонент для форматирования числа в 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 за отличный инструмент! Мы задокументировали типографику, палитру, иконки, сетку, компоненты, пайпы, директивы и сервисы. А также добавили туда общие вопросы, рекомендации по разработке приложения.
===========
Источник:
habr.com
===========
Похожие новости:
- [Разработка веб-сайтов, JavaScript, Angular, TypeScript] RxJS Challenge: Неделя 1
- [Amazon Web Services, Angular, DevOps] Сам себе DevOps: строим cloud-only CI для веб приложения
- [Программирование, Java] Okta: безопасный доступ к приложениям на Angular + Spring Boot (перевод)
- [JavaScript, Angular, ReactJS] Only 39% of the functions in node_modules are unique in the default Angular project (перевод)
- [JavaScript, Angular, ReactJS] Только 39% функций в node_modules уникальны в дефолтном Angular проекте
- [Angular] Добавляем PWA в Angular приложение
- [Angular, TypeScript] Обмен данными между компонентами Angular
- [Angular] Отслеживание состояния компонентов в Angular c помощью ng-set-state (перевод)
- [Программирование, ReactJS, Управление разработкой, TypeScript] Wrike переходит с Dart на новый стек. Какой?
- [JavaScript, Разработка под iOS, Разработка мобильных приложений, Разработка под Android, ERP-системы] Cordova. Опыт Enterprise-проекта
Теги для поиска: #_angular, #_angular, #_taiga_ui, #_biblioteka_komponentov (библиотека компонентов), #_dokumentatsija_proekta (документация проекта), #_frontendrazrabotka (frontend-разработка), #_blog_kompanii_evroplan (
Блог компании Европлан
), #_angular
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 20-Май 01:27
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 3 месяца |
|
|
Привет! Меня зовут Александр. Я работаю над веб продуктами компании Европлан. У нас порядка 50 веб-разработчиков, более 30 стратегических проектов, постоянный процесс онбординга и подключение коллег из смежных команд, поэтому документация библиотеки компонентов помогает быстро адаптироваться.В этой статье я расскажу про способы документации Angular проектов и покажу как это можно сделать с помощью AddOnDoc из TaigaUI. Как говорят сами создатели Александр Инкин и Роман Седов, это конструктор Lego. И действительно: в нём есть много полезных модулей, которые можно использовать в своём проекте. В этой статье мы рассмотрим модуль AddOnDoc.  Для чего мы документируем проектыОбычно, когда я говорю о библиотеке компонентов, мне нравится начинать свой рассказ с дизайн-систем. Дизайн-системы – это то, что позволяет повысить скорость и качество продуктов. Обычно дизайн-система состоит из следующих компонентов:
npm i @taiga-ui/{cdk,core,kit}
npm i @taiga-ui/addon-doc {
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 — компонент для форматирования числа в 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>
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 Taiga UIЗаключениеВ результате мы получили удобную интерактивную документацию проекта. Спасибо команде taiga ui за отличный инструмент! Мы задокументировали типографику, палитру, иконки, сетку, компоненты, пайпы, директивы и сервисы. А также добавили туда общие вопросы, рекомендации по разработке приложения. =========== Источник: habr.com =========== Похожие новости:
Блог компании Европлан ), #_angular |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 20-Май 01:27
Часовой пояс: UTC + 5