Escrever documentação tornou-se fácil graças ao VuePress

Sempre foi uma questão importante fazer um esforço necessário para conceber, programar e implementar algo que satisfaça vários critérios:

• permite-lhe aceder rapidamente à estrutura de uma aplicação
• permite-lhe pesquisar livremente o conteúdo
• fornece um conjunto de informações técnicas sobre as soluções utilizadas
• suporta a formatação de um texto e um código
• pode ser armazenado no GitHub, de preferência com a possibilidade de fácil implantação.

Não admira que a documentação esteja associada a grandes despesas. Por outro lado, a equipa está a crescer, a integração gera muitos custos e, para isso, o apoio faz constantemente as mesmas perguntas aos programadores. A certa altura, toda a gente sente falta ... VuePress.

VuePress é um gerador de páginas estáticas baseado no Vue.js, que é ótimo para criar documentação. Um bom exemplo pode ser dado pela documentação do Vue.js por si só.

VuePress permite editar textos no formato Markdown com o uso de componentes Vue, que, finalmente, dão uma gama realmente ampla de possibilidades. Basta começar com dois comandos:

npm install -g vuepress

vuepress dev

Por defeito, o VuePress é executado no diretório docs / e cria a sua própria pasta vuepress. Após digitar os comandos acima, ele inicia automaticamente o programa Nó e apresenta a documentação em localhost: 8080 /. Eis um exemplo da estrutura do ficheiro.

Com uma configuração correta, o VuePress irá gerar uma página completa e muito estética. Como pode ver no ecrã acima, a nossa documentação contém dois componentes personalizados - CodeHeading e ColorSample.

Um exemplo mais simples para o início será o CodeHeading.

CódigoCabeçalho.vue

Modelo:

<template>
  <div :class="[ 'code-heading', colorClass ]">
    <slot/>
  </div>
</template>

Estilos:

.cabeçalho do código {
 largura: 100%;
 altura: 40px;
 altura da linha: 40px;
 tamanho da fonte: 12px;
 margem inferior: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 alinhamento do texto: esquerda;
 padding: 0 20px;
 box-sizing: border-box;
 cor: branco;

 &__bad {
   cor de fundo: #cc0000;

   &::after {
     conteúdo: "BAD";
   }
 }

 &__good {
   cor de fundo: #3eaf7c;

   &::after {
     conteúdo: "BOM";
   }
 }

 &__default {
   cor de fundo: #4e6e8e;
 }
}

Guião:

exportar por defeito {
 props: {
   type: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Esta é uma sintaxe padrão de um componente Vue.js, que está facilmente disponível em ficheiros Markdown. Aqui está um exemplo de uma implementação (/docs/Code/javacript.md):

const valueWrappers = wrapper.findAll('.change__value').wrappers;
espera(valueWrappers).to.have.lengthOf(2);

esperar(valueWrappers[0].text()).to.equal('€ 5000');
espera(valueWrappers[1].text()).to.equal('0');

Desta forma, obtivemos uma solução completamente legível para apresentar exemplos de trabalho com um código.

Provavelmente, todos os programadores de front-end já passaram por uma situação em que não tinham a representação HEX de uma cor do design gráfico. E se fosse possível ter sempre a cor à mão e fixar antecipadamente uma determinada paleta? É isso mesmo - a documentação de alguma forma torna nós manter a norma. O resultado pode ser o seguinte:

Neste exemplo, foi utilizado o componente ColorPicker.vue. Não serve apenas para a apresentação de uma determinada cor - ao clicar num círculo, copiamos automaticamente o código HEX para a área de transferência.

Modelo:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Clique para copiar o código HEX"
      >
        <div class="color-sample__input-wrapper">
          <input type="text" class="color-sample__input" :id="hexId" :value="color">
            <div class="color-sample__input-overlay" :style="`background-color: ${ color }`"></div>
        </div>
      </div>
      <p>
        <strong>(( nome ))</strong><br/>
        (( cor ))
      </p>
    </div>
  </div>
</template>

Estilos:

.color-sample {
 exibição: inline-block;
 largura: 45%;
 margem: 15px;

 &__container {
   exibição: flex;
   alinhar-itens: centro;
 }

 &__circle {
   largura: 70px;
   altura: 70px;
   float: left;
   border-radius: 50%;
   display: flex;
   alinhar-itens: centro;
   justify-content: center;
   margem-direita: 20px;
   cursor: pointer;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relative;
 }

 &__input {
   tamanho da fonte: 12px;
   padding: 2px;
   raio da borda: 2px;
   border: 0;
   display: inline-block;
   largura: 60px;
 }

 &__input-overlay {
   posição: absoluta;
   top: 0;
   esquerda: 0;
   direita: 0;
   bottom: 0;
   cor de fundo: branco;
   alinhamento do texto: centro;
 }
}

Guião:

exportar por defeito {
 props: {
   cor: String,
   nome: String
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 métodos: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Um exemplo de uma implementação (/docs/Design/colors.md):

Vale a pena prestar atenção ao motor de busca que foi construído no VuePress:

Com base nos cabeçalhos dos ficheiros Markdown, funciona automaticamente. A configuração da documentação feita desta forma é a seguinte:

module.exports = {
 título: 'Docs',
 themeConfig: {
   sidebar: [
     {
       título: 'Geral',
       collapsable: false,
       filhos: [
         'Geral/introdução.md',
         'General/installation.md'
       ]
     },
     {
       título: 'Design',
       colapsável: false,
       filhos: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       título: 'Código',
       colapsável: false,
       filhos: [
         'Código/geral.md',
         'Código/javascript.md',
         'Código/scss.md',
         'Código/vue.md',
         'Código/traduções.md',
         'Código/git.md',
         'Código/implantação.md'
       ]
     }
   ],
   nav: [
     {
       texto: 'Conhecimento',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       texto: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Com o vuepress construir podemos gerar instantaneamente ficheiros HTML estáticos prontos para publicação rápida com suporte completo de activos.

Vale a pena mencionar que o VuePress permite uma implantação automática em várias plataformas, incluindo o GitHub Pages. Além disso, a possibilidade de criar os seus próprios temas faz do VuePress uma boa solução para blogues.

Se os exemplos acima despertaram a sua curiosidade, para mais informações, recomendo que se familiarize com a documentação oficial do VuePress projeto.

Ler mais:

• Otimizar o código com Query Objects
• Tutorial básico do Vue.js. Como começar com esta estrutura?
• Segurança em pacotes Javascript
• GraphQL: lições aprendidas em produção