Scrivere la documentazione è diventato facile grazie a VuePress

È sempre stato un problema importante fare lo sforzo necessario per progettare, programmare e implementare qualcosa che soddisfi diversi criteri:

• permette di accedere rapidamente alla struttura di un'applicazione
• consente di ricercare liberamente i contenuti
• fornisce una serie di informazioni tecniche sulle soluzioni utilizzate
• supporta la formattazione di un testo e di un elemento codice
• possono essere archiviati su GitHub, preferibilmente con la possibilità di un facile deployment.

Non c'è da stupirsi che la documentazione sia associata a spese ingenti. D'altra parte, la squadra è in crescita, l'onboarding genera molti costi e per questo il supporto pone costantemente le stesse domande agli sviluppatori. A un certo punto, a tutti manca... VuePress.

VuePress è un generatore di pagine statiche basato sul metodo Vue.js, che è ottimo per creare documentazione. Un buon esempio può essere dato dalla stessa documentazione di Vue.js.

VuePress consente di modificare i testi in formato Markdown con l'uso dei componenti Vue, che, infine, offrono una gamma davvero ampia di possibilità. Basta iniziare con due comandi:

npm install -g vuepress

vuepress dev

Per impostazione predefinita, VuePress viene eseguito nella directory docs / e vi crea la propria cartella vuepress. Dopo aver immesso i comandi precedenti, viene avviato automaticamente il programma Nodo e visualizza la documentazione su localhost: 8080 /. Ecco un esempio della struttura del file.

Con una configurazione adeguata, VuePress genererà una pagina completa e molto estetica. Come si può vedere nella schermata qui sopra, la nostra documentazione contiene due componenti personalizzati: CodeHeading e ColorSample.

Un esempio più semplice per l'inizio sarà CodeHeading.

CodeHeading.vue

Modello:

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

Stili:

.code-heading {
 larghezza: 100%;
 altezza: 40px;
 line-height: 40px;
 font-size: 12px;
 margine inferiore: -20px;
 bordo-alto-sinistra-raggio: 6px;
 bordo-alto-destra-raggio: 6px;
 text-align: left;
 imbottitura: 0 20px;
 box-sizing: border-box;
 colore: bianco;

 &__cattivo {
   colore di sfondo: #cc0000;

   &::after {
     contenuto: "BAD";
   }
 }

 &__buono {
   colore di sfondo: #3eaf7c;

   &::after {
     contenuto: "GOOD";
   }
 }

 &__default {
   colore di sfondo: #4e6e8e;
 }
}

Script:

Esportazione predefinita {
 oggetti di scena: {
   tipo: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Questa è la sintassi standard di un componente Vue.js, facilmente reperibile nei file Markdown. Ecco un esempio di implementazione (/docs/Code/javacript.md):

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

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

In questo modo, abbiamo ottenuto una soluzione completamente leggibile per presentare esempi di lavoro con un codice.

Probabilmente ogni sviluppatore di frontend si è trovato in una situazione in cui mancava la rappresentazione HEX di un colore del progetto grafico. E se si potesse avere sempre il colore a portata di mano e fissare in anticipo una determinata tavolozza? Esatto: la documentazione ci costringe in qualche modo ad attenerci allo standard. Il risultato potrebbe essere il seguente:

In questo esempio è stato utilizzato il componente ColorPicker.vue. Non serve solo a presentare un determinato colore: facendo clic su un cerchio, si copia automaticamente il codice HEX negli appunti.

Modello:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Fare clic per copiare il codice 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/>
        (( colore ))
      </p>
    </div>
  </div>
</template>

Stili:

.color-sample {
 visualizzazione: inline-block;
 larghezza: 45%;
 margine: 15px;

 &__contenitore {
   display: flex;
   align-items: center;
 }

 &__circolo {
   larghezza: 70px;
   altezza: 70px;
   float: sinistra;
   raggio del bordo: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-right: 20px;
   cursore: puntatore;
   bordo: 1px solid #cfd4db;
 }

 &__input-wrapper {
   posizione: relativa;
 }

 &__input {
   dimensione del carattere: 12px;
   padding: 2px;
   raggio del bordo: 2px;
   bordo: 0;
   visualizzazione: inline-block;
   larghezza: 60px;
 }

 &__input-overlay {
   posizione: assoluta;
   top: 0;
   sinistra: 0;
   destra: 0;
   bottom: 0;
   colore di sfondo: bianco;
   text-align: center;
 }
}

Script:

Esportazione predefinita {
 oggetti di scena: {
   colore: Stringa,
   nome: stringa
 },
 computed: {
   hexId() {
     restituisce `color-${this.color.replace("#", "")}`;
   }
 },
 metodi: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Un esempio di implementazione (/docs/Design/colors.md):

Vale la pena di prestare attenzione al motore di ricerca integrato in VuePress:

In base alle intestazioni dei file Markdown, funziona automaticamente. La configurazione della documentazione realizzata in questo modo è la seguente:

module.exports = {
 titolo: 'Docs',
 themeConfig: {
   sidebar: [
     {
       titolo: 'Generale',
       collapsable: false,
       bambini: [
         'Generale/introduzione.md',
         'Generale/installazione.md'
       ]
     },
     {
       titolo: 'Design',
       collapsable: false,
       bambini: [
         'Design/colori.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       titolo: 'Codice',
       collapsable: false,
       figli: [
         'Codice/generale.md',
         'Codice/javascript.md',
         'Codice/scss.md',
         'Codice/vue.md',
         'Codice/traduzioni.md',
         Codice/git.md
         'Codice/deployment.md'
       ]
     }
   ],
   nav: [
     {
       testo: 'Conoscenza',
       elementi: [
         { testo: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       testo: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       testo: 'Documenti su GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Con il vuepress costruire possiamo generare istantaneamente file HTML statici pronti per una rapida pubblicazione con il supporto completo delle risorse.

Vale la pena ricordare che VuePress consente la distribuzione automatica su varie piattaforme, tra cui GitHub Pages. Inoltre, la possibilità di creare temi personalizzati rende VuePress un'ottima soluzione per i blog.

Se gli esempi sopra riportati hanno suscitato la vostra curiosità, per maggiori informazioni vi consiglio di consultare la documentazione ufficiale dell'VuePress progetto.

Per saperne di più:

• Ottimizzazione del codice con gli oggetti di query
• Tutorial sulle basi di Vue.js. Come iniziare con questo framework?
• Sicurezza nei pacchetti Javascript
• GraphQL: lezioni apprese in produzione