Как мы создаем документацию по пользовательскому интерфейсу в Trabe

В Trabe нам нравится использовать docz для документирования наших компонентов React UI.

Docz - это инструмент нулевой конфигурации для написания документации, используя только уценку и javascript.

Он основан на MDX, который позволяет вам импортировать и экспортировать код из вашего проекта и использовать JSX в документах с уценкой. Он также предоставляет готовые к использованию компоненты, которые упрощают создание ваших документов.

Почему нам это нравится

Это дает вам полную свободу создавать свои документы, и вы можете видеть изменения в реальном времени, пока вы их пишете.

Он сочетает в себе удобочитаемость markdown и мощь компонентов React.

Поскольку MDX использует экосистему замечаний / пересказов, вы можете использовать ее обширную коллекцию плагинов при написании файлов.

Начальная настройка

Установите его с помощью yarn add docz --dev и начните писать .mdx файлы. Они могут пойти куда угодно внутри проекта.

Теперь просто запустите docz dev и перейдите к http: // localhost: 3000, чтобы посмотреть результаты. Если нет .mdx файлов, это будет просто пустая страница.

Этот сервер разработки - тот, который вы будете использовать при написании документации, и, вероятно, единственный, который вам понадобится. Если вам нужно опубликовать свои документы, команда docz build сгенерирует их статическую версию.

Добавление этих двух сценариев на package.json - удобный способ выполнения обеих команд:

{
  "name": "your-proyect",
  "scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build"
  },
  "devDependencies": {
    "docz": "latest"
  }
}

Написание документации

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

/components/
├── button
│   ├── button.css
│   ├── button.jsx
│   ├── button.mdx
│   ├── button.test.jsx
│   └── index.js
├── ...

В типичном .mdx файле docz есть обложка a-la Jekyll, смешанные импорт и уценка. с компонентами, например:

---
name: Button
menu: Components
route: /components/button
---
import Button from './Button'
# The button
Behold the awesome Button Component
<Button>Click</Button>

Настройки, представленные в начале, будут использоваться для настройки структуры веб-документации. По умолчанию каждый документ может иметь следующие основные свойства: name, menu и route.

  • Заголовок страницы компонента определяется с помощью name.
  • Если предоставляется, route задает URL, отличный от представления пути к файлу компонента в виде пунктирной линии по умолчанию.
  • Если вы назначите одну и ту же строку menu нескольким файлам, они будут сгруппированы на боковой панели.

Если ваш сервер разработки все еще работает (обратите внимание, что при добавлении новых файлов вам, возможно, придется его перезапустить), переход к /components/button покажет вам красивый веб-сайт с меню боковой панели с использованием темы по умолчанию.

Обратите внимание, как раздел Button сгруппирован в меню Components, как мы определили в наших настройках.

Можно добавить дополнительные свойства документа и использовать их в своих пользовательских темах.

Встроенные компоненты

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

import { Playground, PropsTable } from "docz";

<PropsTable />

Это поможет вам объяснить, как использовать ваш компонент, используя его PropTypes. Если вы указали их в своем компоненте следующим образом:

Использование <PropsTable of={Button} /> приведет к визуализации красивой таблицы props компонента: имени, типа, значения по умолчанию и описания.

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

<Playground />

Вы уже объяснили свой компонент, возможно, отрендерили его в качестве примера с разными реквизитами и показали, как его использовать. Что теперь?.

Компонент Playground позволяет создать пример, который читатель может изменить и поиграть. Он также показывает визуализированный HTML-код компонента, но только исходной неотредактированной версии docz версии v0.12.9.

## Play with the button

<Playground>
  <h2> The button </h2>
  <Button> Default </Button>
</Playground>

Отрендерит это:

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

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

Обратите внимание, что в этом примере мы не используем свойства класса, поскольку внутри docz у нас нет доступа к этой функции.

Вы можете ознакомиться с полным примером компонента и его документацией здесь. Обратите внимание, что, даже будучи нулевой конфигурацией в этом примере, мы используем doczrc.js для изменения конфигурации сборщика, чтобы мы могли использовать CSSModules.

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

Эта простота и возможности настройки являются основными причинами, по которым мы используем docz во всех наших новых проектах.