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

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

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

Для поддержания документации в актуальном состоянии, документация генерируется исходя из кода компонентов и сопутствующих комментариев.

За парсинг и генерацию доки отвечают пакеты vue-docgen-api и vue-docgen-cli + shared-front/docs/vue-docgen для связки с @nuxt-themes/docus.

Пример описания props

    /**
     * Html тег компонента
     */
    tag: {
      type: String,
      default: '',
    },

    /**
     * Ссылка для перехода
     */
    href: {
      type: [String, EduLink],
      default: '',
    },

    /**
     * Определяет будет ли жирным шрифт в кнопке
     */
    bold: {
      type: Boolean,
      default: true,
    },

    /**
     * Цвет кнопки. values базовых цветов
     * @values 'primary', 'secondary', 'success', 'error', 'warning'
     */
    color: {
      type: String as PropType<ColorsType>,
      default: 'primary' as ColorsType,
      validator: (value: ColorsType) => [...colors, 'none'].includes(value),
    },

    /**
     * Размер кнопки
     * @values 'none', 'table-action', 'small', 'medium', 'big'
     */
    size: {
      type: String as PropType<SizesType>,
      default: 'medium' as SizesType,
      validator: (value: SizesType) => sizes.includes(value),
    },

    /**
     * Атрибут `type` для тега `button`.
     * @values 'submit', 'reset', 'button'
     */
    type: {
      type: String as PropType<ButtonTypeType>,
      default: 'button' as ButtonTypeType,
    },

    /**
     * Название иконки из библиотеки [FontAwesomeIcon](https://fontawesome.com) в виде `fa-solid fa-user` или `solid/user fas/user`.
     */
    icon: {
      type: [String, Object, Array],
      default: '' as IconName,
    },

    /**
     * Расположение иконки относительно текста
     * @values 'left', 'right'
     */
    iconPosition: {
      type: String as PropType<IconPositionsType>,
      default: 'left' as IconPositionsType,
      validator: (value: IconPositionsType) => iconPositions.includes(value),
    },

    /**
     * Делает кнопку с прозрачным фоном и цветной границей
     */
    outline: { type: Boolean, default: false },

    /**
     * Делает кнопку круглой
     */
    round: { type: Boolean, default: false },

    /**
     * Открывает ссылку в новой вкладке (имеет смысл только если указан `href`)
     */
    newTab: { type: Boolean, default: false },

    /**
     * Добавляет к атрибуту `rel` значение `'noopener noreferrer'` (имеет смысл только если указан `href`)
     */
    away: { type: Boolean, default: false },

    /**
     * Состояние кнопки находится в режиме ожидания
     */
    pending: { type: Boolean, default: false },

    /**
     * Устанавливает атрибут `disabled` у элемента кнопки
     */
    disabled: { type: Boolean, default: false },
  },

Более подробные примеры есть в документации vue-styleguidist

Сканируются все .vue файлы внутри shared-front/lib кроме EXAMPLE.vue

Ручная документация

Помимо автодоки присутствует ручная документация, например для css переменных или добавления примеров. Ручную документация можно писать рядом с компонентом в файле README.md

Примеры

Для большинства компонентов необходимо создавать примеры для составления более полной картины того, как выглядит компонент.

Сам пример представляет собой простой .vue компонент

Пример использования. Итоговый файл примера один и тот же

// EXAMPLE.vue
<template>
  <div>
    <SfButton>
      Click
    </SfButton>
  </div>
</template>

<script setup>
import SfButton from './index.vue';
</script>

File structure

• index.vue
• index.ts
• EXAMPLE.vue