La rédaction de la documentation est devenue facile grâce à VuePress
Wojciech Bak
La rédaction de la documentation est une norme qui, dans de nombreux projets, devient un luxe. Sa production passe facilement à l'arrière-plan, surtout lorsque la priorité suivante est donnée aux fonctionnalités supplémentaires lors de la phase de développement d'une application dynamique.
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 framework Vue.js, qui est idéal pour créer de la documentation. La documentation de Vue.js 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.
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) :
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>
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 vuepressconstruire 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.