La rédaction de la documentation est devenue facile grâce à VuePress

Il a toujours été important de faire les efforts nécessaires pour concevoir, programmer et mettre en œuvre quelque chose qui réponde à plusieurs critères :

• permet d'accéder rapidement à la structure d'une application
• vous permet d'effectuer librement des recherches dans le contenu
• fournit un ensemble d'informations techniques sur les solutions utilisées
• prend en charge le formatage d'un texte et d'un code
• peut être stocké sur GitHub, de préférence avec une possibilité de déploiement facile.

Il n'est pas étonnant que la documentation soit associée à des dépenses importantes. D'autre part, la équipe se développe, l'onboarding génère beaucoup de coûts, et pour cela le support pose constamment les mêmes questions aux développeurs. À un moment donné, tout le monde manque ... VuePress.

VuePress est un générateur de pages statiques basé sur le système Vue.js, qui est idéal pour créer de la documentation. La documentation de Vue.js en est un bon exemple.

VuePress vous permet d'éditer des textes au format Markdown à l'aide des composants Vue, qui offrent finalement un large éventail de possibilités. Il suffit de commencer par deux commandes :

npm install -g vuepress

vuepress dev

Par défaut, VuePress s'exécute dans le répertoire docs / et y crée son propre dossier. vuepress. Après avoir entré les commandes ci-dessus, il démarre automatiquement le programme Nœud et affiche la documentation sur localhost : 8080 /. Voici un exemple de la structure du fichier.

Avec une configuration adéquate, VuePress génère une page complète et très esthétique. Comme vous pouvez le voir sur l'écran ci-dessus, notre documentation contient deux composants personnalisés - CodeHeading et ColorSample.

Un exemple plus simple pour le début sera le CodeHeading.

CodeHeading.vue

Modèle :

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

Styles :

.code-heading {
 width : 100% ;
 hauteur : 40px ;
 hauteur de ligne : 40px ;
 font-size : 12px ;
 margin-bottom : -20px ;
 bordure-haut-gauche-radius : 6px ;
 bordure-top-radius-droit : 6px ;
 alignement du texte : à gauche ;
 padding : 0 20px ;
 taille de la boîte : border-box ;
 couleur : blanc ;

 &__bad {
   couleur de fond : #cc0000 ;

   &::after {
     content : "MAUVAIS" ;
   }
 }

 &__good {
   couleur de fond : #3eaf7c ;

   &::after {
     content : "BON" ;
   }
 }

 &__default {
   couleur de fond : #4e6e8e ;
 }
}

Le scénario :

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

Il s'agit d'une syntaxe standard d'un composant Vue.js, qui est facilement disponible dans les fichiers Markdown. Voici un exemple d'implémentation (/docs/Code/javacript.md) :

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

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

Nous avons ainsi obtenu une solution tout à fait lisible pour présenter des exemples de travail avec un code.

Il est probable que tous les développeurs frontaux se soient déjà retrouvés dans une situation où ils ne disposaient pas de la représentation HEX d'une couleur de la conception graphique. Et si vous pouviez toujours avoir les couleurs à portée de main et fixer une certaine palette à l'avance ? C'est exact - la documentation nous oblige en quelque sorte à nous en tenir à la norme. Le résultat peut ressembler à ce qui suit :

Dans cet exemple, le composant ColorPicker.vue a été utilisé. Il ne sert pas seulement à présenter une couleur donnée - en cliquant sur un cercle, nous copierons automatiquement le code HEX dans le presse-papiers.

Modèle :

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Cliquez pour copier le code 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>(( nom ))</strong><br/>
        (( couleur ))
      </p>
    </div>
  </div>
</template>

Styles :

.color-sample {
 display : inline-block ;
 largeur : 45% ;
 margin : 15px ;

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

 &__circle {
   width : 70px ;
   hauteur : 70px ;
   float : left ;
   border-radius : 50% ;
   affichage : flex ;
   align-items : center ;
   justify-content : center ;
   margin-right : 20px ;
   curseur : pointer ;
   border : 1px solid #cfd4db ;
 }

 &__input-wrapper {
   position : relative ;
 }

 &__input {
   font-size : 12px ;
   padding : 2px ;
   border-radius : 2px ;
   border : 0 ;
   display : inline-block ;
   width : 60px ;
 }

 &__input-overlay {
   position : absolute ;
   top : 0 ;
   gauche : 0 ;
   right : 0 ;
   bas : 0 ;
   couleur de fond : blanc ;
   text-align : center ;
 }
}

Le scénario :

export default {
 props : {
   color : String,
   name : String
 },
 computed : {
   hexId() {
     return `color-${this.color.replace("#", "")}` ;
   }
 },
 methods : {
   copyToClipboard() {
     const label = document.getElementById(this.hexId) ;
     label.select() ;
     document.execCommand("copy") ;
   }
 }
} ;

Un exemple de mise en œuvre (/docs/Design/colors.md) :

Il convient de prêter attention au moteur de recherche intégré à VuePress :

Basé sur les en-têtes des fichiers Markdown, il fonctionne automatiquement. La configuration de la documentation réalisée de cette manière est la suivante :

module.exports = {
 title : 'Docs',
 themeConfig : {
   sidebar : [
     {
       title : 'General',
       collapsable : false,
       children : [
         'General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title : 'Design',
       collapsable : false,
       children : [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title : 'Code',
       collapsable : false,
       children : [
         'Code/general.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         'Code/git.md',
         'Code/deployment.md'
       ]
     }
   ],
   nav : [
     {
       text : "Connaissances",
       items : [
         { text : 'VueSchools', link : 'https://vueschool.io/' }
       ]
     },
     {
       text : 'Codest',
       link : 'https://codesthq.com'
     },
     {
       text : "Docs on GitHub",
       link : 'https://github.com/'
     }
   ]
 }
}

Avec la vuepress construire nous pouvons instantanément générer des fichiers HTML statiques prêts pour une publication rapide avec un support complet.

Il convient de mentionner que VuePress permet un déploiement automatique sur diverses plateformes, y compris les pages GitHub. En outre, la possibilité de créer vos propres thèmes fait de VuePress une très bonne solution pour les blogs.

Si les exemples ci-dessus ont éveillé votre curiosité, pour plus d'informations, je vous recommande de vous familiariser avec la documentation officielle de VuePress. projet.

En savoir plus :

• Optimiser le code avec les objets de requête
• Tutoriel sur les bases de Vue.js. Comment commencer avec ce framework ?
• Sécurité dans les paquets Javascript
• GraphQL : leçons apprises en production