Документация

Всегда обновляйте документацию на сайте documentation site через папку src-docs и файл CHANGELOG.md в том же PR, который содержит функциональные изменения. Мы делаем это одновременно, чтобы наши примеры не расходились с реальными компонентами. В этом смысле относитесь к документации так же, как к тестам.

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

• Наиболее распространённые варианты использования компонента.
• Как компонент обрабатывает крайние случаи, например, переполненное содержимое, текстовое или основанное на элементах содержимое.
• Различные состояния компонента, например, отключённое, выбранное, пустое содержимое, состояние ошибки.

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

Вот наши рекомендации по форматированию документации:

• Всегда используйте предложения со строчными буквами для заголовков страниц и разделов. Пример: «Этот компонент что-то делает».
• При ссылке на имя компонента заключайте его в теги <strong>. Пример: <strong>EuiComponent</strong>.
• При обращении к имени компонента всегда включайте префикс Eui, если только вы не ссылаетесь на общий термин. Пример: EuiFlyout против flyout.
• Заключайте ссылки на имена свойств и элементы в блоки <EuiCode>. Пример: <EuiCode>propName</EuiCode>.
• Если ссылка на код представляет собой более чем одно имя свойства или значение, добавьте тип языка. Пример: <EuiCode language="js">propName=true</EuiCode>.
• Когда вы ссылаетесь на другой компонент EUI в описании или примере компонента, оберните ссылку в ссылку на компонент. Пример: <Link to="/component/url><strong>EuiComponent</strong><Link>.

Ссылки между страницами/компонентами документации EUI

В случаях, когда вы хотите предоставить ссылку на другой компонент EUI, упомянутый в описании компонента или в примере, воспользуйтесь преимуществами react-router, который используется для маршрутизации в документации EUI. Помимо преимущества коротких имён путей, react-router будет учитывать среду и предоставлять правильный URL как для разработки, так и для производственных местоположений.

Основной пример:

import {
  Link,
} from 'react-router-dom';

// ...

Consult the larger <Link to="/guidelines/colors">color guidelines</Link> page
for a better explanation about passing color contrast.

Ссылки на внешние ресурсы

При обращении к внешним сайтам или ресурсам используйте компоненты EUI, которые принимают свойство href, например EuiLink.

Основной пример:

import {
  EuiLink,
} from '/src/components';

// ...

<EuiLink href="https://github.com/elastic/eui/blob/master/src/global_styling/mixins/_shadow.scss">View the Sass code for shadow mixins</EuiLink>.

Добавление фрагментов кода

Есть пара тем, о которых следует помнить при добавлении фрагментов:

Спросите себя:

• Предоставляет ли этот фрагмент потребителю всё необходимое для работы компонента?
• Предоставляет ли этот фрагмент детали конкретного объекта, необходимого компоненту для работы?
• Если он не предоставляет ни того, ни другого, и для работы компонента требуется весь демо-код JS, то, вероятно, лучше не добавлять фрагмент.

Будьте последовательны:

• Не используйте this., но пишите фрагмент как функциональный компонент.
• Используйте описательные переменные JS вместо потребительских строк, функций, состояний и типов узлов.
• Все остальные реквизиты, такие как перечисления, должны быть написаны с соответствующими типами значений.

<EuiPopover
  id={popoverId}
  button={button}
  isOpen={isPopoverOpen}
  closePopover={closePopover}
  anchorPosition="downLeft"
>
  <!-- Popover content -->
</EuiPopover>

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

<EuiLink href="#"><!-- Link text --></EuiLink>

<EuiLink href="#" color="secondary">
  <!-- Colored link text -->
</EuiLink>

• Используйте HTML-комментарии, чтобы предложить, каким может быть children.

<EuiText **Сниппет должен иллюстрировать, когда компонент требует, чтобы его дочерние элементы были обернуты определенным тегом.**

``` js
<EuiCallOut>
  <p><!-- Content --></p>
</EuiCallOut>

Когда компонент содержит один дочерний элемент, сниппет должен это проиллюстрировать. Соблюдайте лучшие практики, предоставляя описание.

<EuiTitle>
  <h2><!-- По умолчанию средний размер. Измените уровень заголовка в зависимости от контекста. --></h2>
</EuiTitle>

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

<EuiSteps
  steps={[
    {
      title: 'Шаг 1',
      children: <p>Сделайте это первым</p>,
    },
  ]}
/>

Changelog

Любые обновления в папке src/ требуют записи в файле CHANGELOG.md. Документационные изменения не требуют этого. Вот наши рекомендации по обновлению файла:

• Добавьте свои изменения в подраздел master файла CHANGELOG.md.
• Для каждого существенного изменения в PR добавьте элемент списка: исправленные ошибки, новые функции, новые компоненты или изменения в публичном API.
• В элементе списка всегда указывайте ссылку на соответствующие запросы на вытягивание.
• Дайте краткое описание того, что изменилось, убедившись, что оно информативно для потребителей, которые могут быть не осведомлены о деталях реализации.
• Избегайте документирования внутренних изменений реализации, которые не влияют на публичный интерфейс.
• Пишите свою запись в прошедшем времени, начиная с глагола (например, «Добавлено...», «Исправлено...»).