Автогенерация документации

Stencil предоставляет удобный механизм для автоматической генерации документации компонентов, что значительно упрощает процесс разработки, поддержки и использования библиотек компонентов. Этот функционал особенно полезен для крупных проектов и позволяет поддерживать актуальность документации, синхронизируя её с изменениями в коде компонентов. В Stencil документация формируется в формате JSDoc, что позволяет интегрировать автогенерацию в процессы CI/CD, автоматически создавая документацию при каждом изменении кода.

Настройка автогенерации документации

Stencil поддерживает создание документации из аннотаций JSDoc, встроенных в исходный код компонентов. Для того чтобы включить автоматическую генерацию документации, необходимо использовать соответствующие параметры в конфигурационном файле stencil.config.ts.

Пример базовой конфигурации автогенерации документации:

import { Config } from '@stencil/core';

export const config: Config = {
  namespace: 'myComponentLibrary',
  generateDocumentation: true,
  outputTargets: [
    {
      type: 'docs',
      dir: './docs',
    },
  ],
};

В этом примере включается опция generateDocumentation, которая отвечает за создание документации, а также настраивается выходной каталог, в который будет сохранена сгенерированная документация.

Структура документации

Генерируемая документация имеет структуру, аналогичную документации JSDoc. Она будет включать описание компонентов, их методов, свойств и событий, если они были корректно аннотированы в исходном коде.

Пример аннотации компонента с использованием JSDoc:

/**
 * Кнопка, которая изменяет текст при нажатии.
 * @component
 * @name my-button
 * @description Этот компонент представляет собой кнопку, которая меняет свой текст при клике.
 */
@Component({
  tag: 'my-button',
  styleUrl: 'my-button.css',
  shadow: true,
})
export class MyButton {
  /**
   * Текст, отображаемый на кнопке.
   * @type {string}
   * @default 'Click me!'
   */
  @Prop() label: string = 'Click me!';

  @Event() buttonClick: EventEmitter;

  handleClick() {
    this.buttonClick.emit();
  }

  render() {
    return (
      <button onCl ick={() => this.handleClick()}>{this.label}</button>
    );
  }
}

В данном примере компонент описан с помощью аннотаций JSDoc. Такие аннотации позволяют Stencil автоматом извлекать важные метаданные для генерации документации:

  • @component — указывает, что это компонент.
  • @name — задаёт имя компонента.
  • @description — описывает компонент, его функционал.
  • @type — указывает тип данных свойства.
  • @default — показывает значение по умолчанию для свойства.

Автогенерация документации извлекает эти метаданные и формирует на их основе структурированную документацию.

Взаимодействие с документацией

После того как документация сгенерирована, она сохраняется в указанной директории (например, ./docs). Эта документация может быть использована для создания статических сайтов, интеграции с системой документации (например, с использованием Docusaurus или других инструментов) или просто быть доступной в виде HTML-файлов.

Каждый компонент будет представлен на своей странице с подробным описанием его интерфейса: свойств, методов и событий. В документации также могут быть включены примеры использования компонента, что облегчает его внедрение в проекты.

Дополнительные параметры конфигурации

Stencil предоставляет несколько дополнительных параметров для настройки автогенерации документации:

  • docsTypes: Этот параметр позволяет указать, какие типы файлов должны быть включены в документацию. По умолчанию документация генерируется для всех компонентов, но с помощью этого параметра можно ограничить её генерацию только для определённых типов файлов (например, только для компонента или только для интерфейсов).

  • docsDir: Указывает директорию, в которую будет сохранена документация. Это может быть полезно, если необходимо изменить стандартный путь.

Пример настройки дополнительных параметров:

export const config: Config = {
  namespace: 'myComponentLibrary',
  generateDocumentation: true,
  outputTargets: [
    {
      type: 'docs',
      dir: './docs',
      docsTypes: ['component', 'interface'],
    },
  ],
};

Формат документации

Генерируемая документация Stencil будет представлять собой статические HTML-страницы, оформленные в структуре, схожей с документацией на сайте. Включаются следующие разделы:

  1. Список компонентов — все компоненты, доступные в библиотеке.
  2. Описание компонентов — для каждого компонента будут отображаться его описание, доступные свойства, методы и события.
  3. Примеры использования — если в комментариях к коду имеются примеры, они будут отображаться в соответствующем разделе.
  4. Ссылки на внешние зависимости — если компонент зависит от других библиотек или компонентов, такие связи будут отображаться.

Данная структура позволяет пользователю быстро разобраться в использовании компонента и его характеристиках.

Интеграция с другими инструментами

Документация, сгенерированная с помощью Stencil, может быть использована в рамках более сложных инструментов. Например, можно интегрировать её с системой контроля версий, чтобы она автоматически обновлялась с каждым коммитом, или настроить публикацию документации в публичные репозитории, такие как GitHub Pages.

Также можно интегрировать с инструментами для создания документации, например:

  • Docusaurus — позволяет интегрировать сгенерированную документацию Stencil в единую систему документации с красивым пользовательским интерфейсом.
  • GitBook — ещё один популярный инструмент для создания документации, поддерживающий импорт HTML-страниц.

Поддержка типов и интерфейсов

Stencil позволяет документировать не только компоненты, но и TypeScript интерфейсы, классы и типы данных. Использование типов в документации улучшает понимание кода и упрощает интеграцию компонентов в проекты.

Пример документации интерфейса:

/**
 * Интерфейс для описания настроек компонента.
 * @interface
 * @name ButtonSettings
 */
export interface ButtonSettings {
  /**
   * Размер кнопки.
   * @type {string}
   * @default 'medium'
   */
  size?: string;
  /**
   * Цвет кнопки.
   * @type {string}
   * @default 'blue'
   */
  color?: string;
}

Генерация документации для интерфейсов помогает понять, как правильно использовать типы в компонентах и какие настройки доступны для кастомизации.

Заключение

Автогенерация документации в Stencil упрощает процесс разработки и поддержания актуальности документации для компонентов. Благодаря интеграции с JSDoc и гибкой настройке можно автоматически генерировать подробную, структурированную документацию, которая всегда будет синхронизирована с кодом. Это повышает удобство разработки и облегчает взаимодействие с компонентами для других разработчиков и пользователей библиотеки.

Оглавление