Même le meilleur projet open-source peut échouer sans documentation complète. La documentation interne est tout aussi cruciale, empêchant les questions et réponses répétitives et garantissant la continuité des connaissances même avec les changements de personnel. Les directives de codage bien documentées favorisent la cohérence de la base de code.

Pour une documentation approfondie, Markdown offre une alternative supérieure au HTML brut. Cependant, les limitations de Markdown peuvent être surmontées en intégrant HTML directement dans les fichiers de Markdown, y compris des éléments personnalisés pour les systèmes de conception à l'aide de composants Web. Pour React (et des cadres compatibles JSX comme Preact ou Vue), MDX fournit une intégration transparente.

Cet article donne un aper?u de haut niveau des outils de création de guide de documentation et de style. Bien que tous n'utilisent pas le MDX, son adoption augmente rapidement.

Comprendre MDX

Un fichier .mdx reflète la syntaxe de Markdown standard mais permet l'importation et l'intégration de composants JSX interactifs. La prise en charge des composants Vue est actuellement en alpha. MDX s'intègre facilement à Create React App, et les plugins existent pour Next.js et Gatsby. Docusaurus version 2 présentera également une prise en charge intégrée.

Docusaurus: une puissance de documentation

Développé par Facebook (à l'exclusion de React), Docusaurus est utilisé par de nombreux grands projets open-source (Redux, plus joli, Gulp, Babel). Sa polyvalence s'étend au-delà de la documentation frontale. Tout en utilisant React en interne, Docusaurus ne nécessite aucune connaissance de réaction à utiliser. Il transforme les fichiers Markdown en sites de documentation bien structurés et visuellement attrayants.

Les sites Docusaurus peuvent incorporer des blogs basés sur Markdown et inclure Prism.js pour la mise en évidence de la syntaxe transparente. Sa popularité est évidente, ayant été élue le nouvel outil de 2018 sur Stackshare.

Solutions de documentation alternatives

Alors que Docusaurus est spécialisé dans la documentation, de nombreuses alternatives existent. Les solutions personnalisées sont réalisables en utilisant diverses langages arrière, CMSS ou générateurs de sites statiques. React, le système de conception d'IBM, Apollo et Ghost CMS, par exemple, exploitent Gatsby, un générateur de site statique polyvalent souvent utilisé pour les blogs. Vuepress gagne du terrain dans l'écosystème Vue. MKDOCS, un générateur de sites statiques open source écrit en Python, offre une configuration YAML directe. GitBook, une option payante populaire, offre un accès gratuit aux équipes open-source et à but non lucratif. Pour une documentation interne plus simple, les capacités de rendu de Markdown de GitHub sont une option viable.

Documentation des composants: Docz, Storybook et StyleGuidist

Les guides de style et les systèmes de conception ont gagné en popularité. Les cadres basés sur les composants (comme React) et les outils associés les ont transformés des projets de vanité en ressources essentielles.

Le livre de contes, Docz et StyleGuidist servent un objectif similaire: afficher des composants interactifs d'interface utilisateur et documenter leurs API. La gestion de nombreux composants avec des états et des styles variables nécessite un catalogue centralisé pour la découverte et la réutilisation. Les guides de style fournissent des aper?us facilement consultables, la promotion de la cohérence visuelle et la prévention des travaux redondants.

Ces outils simplifient l'examen des différents états des composants, surmontant les défis de la reproduction de tous les états dans une application en direct. Le développement de composants isolés permet de se moquer des états difficiles d'accès (par exemple, des états de chargement).

Les commentaires de Dan Green sur les avantages de StoryBook s'appliquent également à Docz et à StyleGuidist:

?Le livre de contes a simplifié la collaboration entre la conception et l'ingénierie. Il élimine le besoin d'une configuration complexe (conteneurs Docker, etc.). Pour Wave, nous gérons les composants que visibles pendant les processus de courte durée et complexes (par exemple, les écrans de chargement). Avant le livre de scénarios, la gestion de ces composants était difficile. Maintenant, Storybook fournit un environnement isolé, un concepteur accessible et des PMS, des éliminaires de diffusion.

- Dan Green, Wave Financial

Au-delà de la visualisation des états et de la liste des accessoires, le contenu écrit (justification de conception, cas d'utilisation, résultats des tests utilisateur) améliore la documentation des composants. L'accessibilité de Markdown le rend idéal pour la documentation collaborative entre les concepteurs et les développeurs. Docz, Styleguidist et Storybook intègrent de manière transparente Markdown avec les composants.

Docz

Actuellement React uniquement (avec prise en charge planifiée pour les composants PREACT, VUE et Web), DOCZ (14 000 GitHub Stars) offre une fonctionnalité conviviale. Il fournit<playground></playground> et<props></props> Composants, directement utilisés dans les fichiers .mdx .

 Import {Playground, props} de "docz";
Bouton d'importation de "../src/button";

## Vous pouvez _Write_ ** Markdown **
### Vous pouvez importer et utiliser des composants

<playground>
  <button>faire un clic</button>
</playground>

Emballage des composants de réaction avec<playground></playground> Crée des aper?us interactifs intégrés.<props></props> Affiche les accessoires de composants, les valeurs par défaut et l'état requis.

<props of="{Button}"></props>

L'approche basée sur MDX de Docz est intuitive et efficace, offrant une excellente intégration de Gatsby.

Guidiste

StyleGuidist utilise des blocs de code Markdown (Triple Backticks) dans des fichiers .md standard au lieu de MDX.

 `` JS
 console.log ('cliquez sur ")

<code></code>

 <code>>Push Me</code>

Les blocs de code Tagged js , jsx ou javascript rendent les composants de réaction interactifs. Le code est modifiable, fournissant des commentaires visuels instantanés. StyleGuidist génère automatiquement des tables d'hélice à partir de déclarations de propulpypes, de flux ou de dactylographie. Il prend en charge React et Vue.

Livre de contes

Storybook (36 000 Github Stars) est un environnement de développement de composants d'interface utilisateur. Au lieu de Markdown / MDX, il utilise des fichiers JavaScript pour des histoires (représentant des états de composants).

 histoires de (?bouton?, module)
  .add ('handicap', () => (
    <button disabled>Lorem Ipsum</button>
  ))

L'approche de StoryBook est moins intuitive que Docz et StyleGuidist. Cependant, sa popularité et son support cadre étendu (React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte, HTML) sont remarquables. La documentation nécessite actuellement des addons, mais les versions futures incorporeront MDX, inspirée par Docz.

 # Bouton

Certains _notes_ sur votre bouton écrit avec ** Markdown Syntax **.


<button>Lorem Ipsum</button>

La prochaine fonction DOCS de StoryBook promet des améliorations significatives.

Conclusion

La valeur des bibliothèques de motifs est largement reconnue. Les bibliothèques bien exécutées favorisent la cohérence visuelle et la cohésion des produits. Bien que ces outils ne remplacent pas l'expertise de conception et de CSS, Docz, StoryBook et StyleGuidist fournissent d'excellentes solutions pour communiquer efficacement les systèmes de conception au sein des organisations.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!