Por: @hugoc
Publicado em: 2018-09-17

Documentação dos componentes IMD (Itflex Material Design)

Para ajudar no desenvolvimento dos componentes imd e também no auxílio de como usa-los, com isso veio a necessidade de criar uma documentação iterativa

A pesquisa

Em cima da necessidade apontada foi feito o estudo de duas bibliotecas que auxiliam na documentação

• vue design system
• vue styleguidist

Para aprofundar mais os testes foi levado em conta:

• facilidade de implantação no projeto atual
• facilidade de desevolvimento das docs
• layout limpo e de fácil leitura
• interatividade com os componentes

Vue Design System

Não foi realizado muitos testes em cima da biblioteca pois já na implantação no projeto atual foi identificado dificuldades:

• projeto da doc deve ficar em projeto separado
• difícil implantação

Vue Styleguidist

A biblioteca escolhida para o desenvolvimento pois atendeu a maior parte dos pontos listados a cima.

Instalação

Foi fácil,  apenas seguir o guia na doc da própria biblioteca, criando os arquivos de conf de acordo com o que deseja no seu projeto. O Styleguidist já tem integração com o vuetify e i18n basta apenas criar os confs conforme esta na doc.

Criando doc do componente

Após instalar e apontar para o diretório do projeto dos componentes, parte da coleta e criação da informações de cada componente a lib faz automaticamente, como titulo e props.

A documentação é feita dentro do código do própio componente com comentários e tags específicas todas estão documentadas no repositório da lib. Segue algumas usadas nos testes:

Descrição do componente:

/**
  * itflex material designe button.
  * @version 1.0.0
  */
export default {
}

Descrição das props:

props: {
  /**
    * Posicione o elemento absolutamente.
    */
  absolute: {
    type: Boolean,
    required: false,
    default: false,
  },
  /**
    * Vue Router router-link prop.
    */
  append: {
    type: Boolean,
    required: false,
    default: false,
  },
},

Descrição dos métodos e eventos:

methods: {
  clickEvent() {
    this.$emit('click')
    /**
    * É chamado quando o usuário clica no botão.
    *
    * @public
    */
    clickEvent() {
        /**
        * Emite evento de click.
        *
        * @event click
        */
        this.$emit('click')
  },
},

Para adicionar como componente deve ser usado e gerar a iteratividade na página da documentação, existem duas formas, uma dentro do arquivo do próprio componente ou criando um Readme.md dentro da pasta do componente. Na pesquisa foi feito com a segunda opção, para ficar mais separado e melhor entendimento.

Readme.md

Botão básico:

<template>
    <div>
        <imd-button color="primary" @click="clickPrimaryEvent">primary</imd-button>
        <imd-button color="secondary" @click="clickSecondaryEvent">secondary</imd-button>
        <imd-button color="error" @click="clickErrorEvent">error</imd-button>
        <imd-button color="warning" @click="clickWarningEvent">warning</imd-button>
    </div>
</template>

<script>
export default {
  methods: {
    clickPrimaryEvent() {
        alert('Primary')
    },
    clickSecondaryEvent() {
        alert('Secondary')
    },
    clickErrorEvent() {
        alert('Error')
    },
    clickWarningEvent() {
        alert('Warning')
    },
  }
}
</script>

Fazendo isso ele gera o componente e o código para iteração direto com o componente.