Maison >développement back-end >Tutoriel Python >Déploiement de Docs-as-Code sur AWS : création de sites de documentation dynamiques dans MkDocs et Docusaurus
Déploiement de Docs-as-Code sur AWS : création de sites de documentation dynamiques dans MkDocs et Docusaurus
- Mary-Kate Olsenoriginal
- 2024-11-28 05:28:11181parcourir
Dans cet article, je vais vous guider étape par étape pour créer un site de documentation dynamique, adaptable à tout projet, où vous pourrez connecter votre documentation à une base de données pour extraire et afficher des données, garantissant ainsi l'information est toujours à jour. Nous explorerons également comment automatiser l'ensemble du processus, de la génération de contenu au déploiement dans le cloud avec AWS.
La solution inclut la prise en charge des graphiques et des diagrammes, l'intégration continue (CI/CD) à l'aide d'un flux de travail simple dans GitHub Actions et le déploiement automatique à l'aide de Terraform. Commençons !
Qu’est-ce que la documentation en tant que code ?
La documentation et ses mises à jour sont un processus important dans de nombreuses entreprises qui développent des logiciels, souvent réalisées à l'aide de différents outils, dont beaucoup sont des solutions payantes.
C'est pourquoi, ces derniers temps, le concept de "doc as code" a émergé. Cela signifie utiliser les mêmes outils et flux de travail que ceux utilisés dans le développement de logiciels pour gérer, versionner et déployer la documentation.
Cette approche permet non seulement un meilleur suivi de la documentation mais facilite également sa maintenance et garantit l'alignement avec les mêmes bonnes pratiques utilisées en développement logiciel, non seulement dans le code mais aussi dans la documentation.
Outils de documentation sous forme de code
Pour le développement de ces sites, il est essentiel de comprendre certaines pratiques et outils qui nous permettent de mettre en œuvre cette démarche. Vous trouverez ci-dessous une liste détaillée des aspects les plus importants à aborder dans ce tutoriel.
- ? Markdown : Le langage de balisage le plus courant pour la rédaction de documentation en raison de sa simplicité et de son intégration avec les plateformes de contrôle de version et les générateurs de sites statiques.
- ?️ Git : Git permet le versionnage de la documentation tout comme le code. Grâce à Git, chaque modification apportée à la documentation est enregistrée, ce qui permet aux équipes de suivre les modifications, d'annuler les modifications et de collaborer plus efficacement.
- ? Gitflow : cette méthodologie fournit un flux de travail structuré pour gérer les versions et les révisions de la documentation, garantissant que les modifications sont approuvées et testées avant d'atteindre la production. Gitflow facilite également la collaboration entre les équipes, permettant une gestion du changement sécurisée et organisée.
- ☁️ Services Cloud : en utilisant des services comme AWS S3, Netlify ou GitHub Pages, vous pouvez déployer de la documentation à faible coût. Ces services permettent la création de sites statiques rapides, sécurisés et facilement accessibles.
- ? Générateurs de sites statiques : des outils comme Docusaurus, Jekyll ou Hugo convertissent la documentation Markdown en un site Web navigable, vous permettant de créer une documentation riche et organisée sans serveur.
- ? Intégration continue (CI/CD) : les pipelines CI/CD (par exemple, GitHub Actions, GitLab CI ou Jenkins) vous permettent de déployer automatiquement la documentation lorsqu'une nouvelle version est fusionnée ou que des modifications sont approuvées. Cela garantit que la documentation est toujours à jour.
Avantages de Docs-as-Code
- ✅ Cohérence et qualité : En utilisant le contrôle de version et les revues de modifications, la documentation reste cohérente et de haute qualité.
- ⚙️ Automatisation : les outils CI/CD permettent d'automatiser le déploiement de la documentation, réduisant ainsi les temps de mise à jour et minimisant les erreurs.
- ? Collaboration efficace : avec des outils comme Git, les équipes peuvent collaborer sur la création et la maintenance de la documentation sans conflits.
- ? Maintenance simplifiée : La maintenance de la documentation est intégrée au workflow de développement, ce qui facilite les mises à jour à mesure que le code évolue.
? MKDocs
MkDocs est un générateur de sites statiques écrit en ?Python, conçu spécifiquement pour documenter des projets. Son objectif est de simplifier la création de documentation à l'aide de fichiers Markdown, faciles à écrire et à lire.
Avec une configuration minimale, MkDocs convertit les fichiers Markdown en un site Web de documentation navigable et bien structuré, ce qui le rend idéal pour les développeurs et les équipes qui souhaitent maintenir leur documentation à jour.
✏️ Matériel MkDocs
MkDocs Material est un thème avancé pour MkDocs qui suit les directives de conception matérielle de Google.
? Les principales fonctionnalités incluent :
- ? Responsive Design : s'adapte automatiquement à n'importe quelle taille d'écran.
- ? Personnalisation : modifiez facilement les couleurs, les polices, le favicon et le logo pour correspondre à l'identité visuelle de votre projet.
- ? Interface de recherche : la recherche avancée regroupe les résultats et met en évidence les termes recherchés, aidant ainsi les utilisateurs à trouver les informations dont ils ont besoin.
- ⚡ Lazy Loading : implémente le chargement paresseux pour les résultats de recherche, améliorant les performances et réduisant les temps de chargement.
- ? Intégrations : compatible avec Google Analytics, Disqus et GitHub, facilitant l'analyse du trafic, les commentaires des utilisateurs et la connexion directe au référentiel du projet.
✏️ Sirène
Mermaid est une bibliothèque JavaScript permettant de créer des diagrammes et des graphiques à partir de texte. En s'intégrant à MkDocs Material, Mermaid vous permet de générer des visualisations telles que des organigrammes, des diagrammes entité-relation et d'autres graphiques dans la documentation sans outils externes.
? Page dynamique : Jinja
Jinja est une bibliothèque qui permet d'intégrer des variables et des données de dictionnaires Python dans HTML, rendant ainsi les pages Web dynamiques. Cette bibliothèque est couramment utilisée pour générer du HTML dynamique et envoyer des e-mails personnalisés.
? Présentation du Docusaurus
Docusaurus est un projet open source développé par Meta en 2007 qui simplifie la création, le déploiement et la maintenance de sites Web de documentation de manière rapide et efficace. Il permet d'utiliser Markdown et MDX pour rédiger du contenu, tandis que son noyau construit sur React permet une personnalisation complète des styles pour répondre aux besoins spécifiques du projet.
De plus, Docusaurus prend en charge Mermaid via le plugin @docusaurus/theme-mermaid, permettant l'inclusion de graphiques et de diagrammes directement dans la documentation.
? Diagramme en tant que code
Diagram as Code est une approche qui vous permet de créer des diagrammes via du code, plutôt que d'utiliser des outils graphiques traditionnels. Au lieu de créer manuellement des diagrammes, vous écrivez du code dans un fichier texte pour définir la structure, les composants et les connexions de vos diagrammes.
Ce code est ensuite traduit en images graphiques, ce qui facilite son intégration et sa documentation dans les projets logiciels. Il est particulièrement utile pour créer et mettre à jour des diagrammes d'architecture et de flux par programmation.
? Diagramme en tant que code : exemple de création de diagrammes cloud
Comme mentionné précédemment, Diagrammes vous permet de générer des plans en utilisant les icônes des principales technologies cloud. La représentation de ces diagrammes se fait via des nœuds, et dans notre exemple, nous utiliserons tous les nœuds liés au cloud et les services AWS.
Pour plus de détails sur la façon dont j'ai créé cela, vous pouvez lire mon article sur Diagram as Code, et l'implémentation complète peut être trouvée dans ce référentiel :
r0mymendez
/
diagramme en tant que code
Un tutoriel sur la façon de créer un projet de documentation en utilisant la méthodologie « Doc sous forme de diagramme »
? Diagram-as-Code : Création d'une documentation dynamique et interactive pour le contenu visuel
Diagram as Code est une approche qui vous permet de créer des diagrammes via du code au lieu des outils graphiques traditionnels. Au lieu de créer manuellement des diagrammes, vous pouvez écrire du code dans un fichier texte pour définir la structure, les composants et les connexions de vos diagrammes.
Ce code est ensuite traduit en images graphiques, ce qui facilite son intégration et sa documentation dans des projets logiciels, où il est particulièrement utile pour créer et mettre à jour des diagrammes architecturaux et de flux par programmation.
Qu'est-ce que les diagrammes ?
Diagrams est une ?Bibliothèque Python qui implémente l'approche Diagram as Code, vous permettant de créer des diagrammes d'infrastructure architecturale et d'autres types de diagrammes via du code. Avec Diagrams, vous pouvez facilement définir des composants d'infrastructure cloud (tels qu'AWS, Azure et GCP), des éléments de réseau, des services logiciels et bien plus encore, le tout avec seulement quelques lignes de code.
? Avantages du diagramme en tant que code
- ?…
? Cas d'utilisation : création d'un site de documentation pour un projet d'apprentissage automatique
Dans ce cas d'utilisation, je vais créer un site de documentation pour un projet d'apprentissage automatique impliquant ? données hospitalières. L'objectif est de créer un site de documentation interactif en utilisant MkDocs dans un premier temps, puis de le migrer vers Docusaurus. Le site comprendra des composants statiques et dynamiques pour répondre à des exigences spécifiques, telles que l'intégration de diagrammes visuels et la mise à jour dynamique des données à partir d'une base de données SQLite.
? Principales fonctionnalités du site de documentation
- Représentations visuelles : j'intégrerai des diagrammes créés avec Diagrams (Diagram as Code) pour illustrer efficacement l'architecture du pipeline d'apprentissage automatique.
- Mises à jour dynamiques des données : la documentation affichera la version et la date de la dernière mise à jour de manière dynamique, en extrayant ces informations d'une base de données SQLite pour garantir l'exactitude et la pertinence.
- Échantillon de données : La documentation comprendra un échantillon de la table des patients Synthea, présentant des données synthétiques à titre d'exemple.
? Pages du site
Pour cette raison notre site de documentation comportera les pages suivantes :
- ? Accueil : La page d'accueil de la documentation.
- ? Tableaux :Explication des tableaux de données Synthea et leurs utilisations.
- ? Architecture :Un aperçu détaillé de l'architecture de traitement des données, hébergée sur AWS.
- ? Glossaire : Un glossaire des termes utilisés tout au long du projet
Implémentation de MkDocs
Dans cette section, nous passerons en revue les étapes pour mettre en place un projet de documentation à l'aide de MkDocs à partir de zéro et expliquerons sa structure de répertoires organisée.
? Conditions préalables pour MkDocs
Pour commencer, vous devrez installer les bibliothèques ?Python suivantes :
Installer MkDocs et le matériel
pip install mkdocs mkdocs-material
Installez des bibliothèques supplémentaires pour activer la mise à jour dynamique du contenu
pip install aiosql pandas sqlite3 jinja2 shutil
? Mkdocs : configuration du projet
Initialiser le projet
Commencez par créer un nouveau projet MkDocs. Exécutez les commandes suivantes dans votre terminal :
mkdocs new mkdocs cd mkdocs
Cette commande crée un projet MkDocs de base avec une structure par défaut.
Explorez la structure du répertoire
Une fois le site MkDocs créé, vous devez ajouter les fichiers et dossiers suivants, car ils ne sont pas inclus par défaut.
N'oubliez pas que les liens vers le référentiel sont fournis à la fin de cet article pour votre référence, et chaque composant sera expliqué en détail ci-dessous.
pip install mkdocs mkdocs-material
?Mkdocs : Présentation des composants
| Component | Directory | Description |
|---|---|---|
| Database (db) | db | Contains the SQLite database (hospital.db) and queries (metadata.sql, person.sql) to manage dynamic data. Learn more about managing SQL queries in Python in my previous article: Python Projects with SQL. |
| ?️ Templates & Pages | template | Markdown templates: index.md, tables.md, architecture.md, glossary.md. Supports Mermaid diagrams, embedded images, and database-driven content. |
| ?️ Static Content (docs) | docs | Final site generated by update.py, including images (img/) and dynamic content populated from template. |
| ? Infrastructure (infraestructure) | infraestructure | Terraform scripts (main.tf, variables.tf) to deploy an S3 bucket for documentation hosting. |
? Mkdocs : configuration de mkdocs.yml
Une fois la structure de notre projet configurée, nous la configurerons étape par étape, en commençant par le fichier mkdocs.yml. Ce fichier définit la structure et les paramètres de votre site de documentation. Voici comment cela devrait être structuré :
mkdocs.yml
pip install mkdocs mkdocs-material
Dans ce fichier de configuration, vous pourrez principalement voir dans la section nav les pages qui seront accessibles depuis le menu. Ensuite, nous spécifions l’extension Mermaid, qui sera expliquée dans la section suivante. Enfin, la section theme applique le thème Material, permettant le style et les composants disponibles dans cette bibliothèque.
✏️ Mkdocs : Extension Sirène
Comme mentionné précédemment, Mermaid est une bibliothèque JavaScript permettant de créer des diagrammes et des graphiques à partir de texte. Ci-dessous, nous verrons quelques exemples. Dans notre cas, nous l'utiliserons pour générer un diagramme Entité-Relation (ERD) sur la page tables de la documentation.
Dans le référentiel, vous pourrez voir comment construire ce code basé sur le diagramme de relation d'entité (ERD) trouvé dans la documentation officielle de Synthea. Vous pouvez également consulter l'exemple de la page tables dans le lien suivant : tables.md.
⚙️ Mkdocs : Contenu dynamique avec Jinja
Pour permettre la génération de contenu dynamique pour notre site de documentation, nous utiliserons Jinja pour traiter les modèles et remplacer les espaces réservés par des données réelles. Vous trouverez ci-dessous une présentation étape par étape :
Configurer un dossier de modèles
Créez un dossier nommé modèles pour stocker tous les fichiers Markdown du site. Ces fichiers doivent inclure des espaces réservés. Par exemple, dans index.md, vous pouvez avoir des espaces réservés tels que {{database.version_date}} et {{database.version}}.Utiliser des espaces réservés
Les espaces réservés sont des variables dynamiques dans les fichiers Markdown. Ces variables seront mises à jour automatiquement à l'aide de dictionnaires Python pour injecter des données pertinentes.-
Générer du contenu dynamique avec update.py
- Préparez vos modèles Markdown en identifiant les sections où des données dynamiques sont requises.
- Utilisez un script Python (update.py), disponible dans mon référentiel, pour traiter les modèles. Le script effectue les tâches suivantes :
- Connexion à la base de données : se connecte à une base de données SQLite pour récupérer les dernières valeurs.
- Rendu de modèle : utilise la bibliothèque Jinja pour remplacer les espaces réservés par les données de la base de données.
- Génération de fichiers : génère les fichiers Markdown mis à jour dans le dossier docs, prêts à être rendus dans MkDocs.
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
En suivant ces étapes, vous pouvez automatiser le processus de mise à jour de votre site de documentation, garantissant ainsi que le contenu reste dynamique et pertinent sans modifications manuelles.
Mise à jour dynamique des tableaux de données
Dans l'exemple suivant, nous mettrons à jour le contenu du fichier tables.md pour afficher un exemple de la table persons de la base de données. Pour ce faire, nous allons créer un espace réservé {{table.person}} dans le fichier Markdown. L'idée est de récupérer dynamiquement les données de la table persons, puis d'utiliser la bibliothèque Jinja avec des pandas pour convertir les résultats de la requête au format de table Markdown.
Voici un exemple de l'apparence du fichier tables.md avec l'espace réservé :
mkdocs new mkdocs cd mkdocs
Le processus est le suivant :
- Interroger la base de données : le script interrogera la table persons de la base de données SQLite pour récupérer les enregistrements pertinents.
- Convertir en Markdown : à l'aide de pandas, les résultats de la requête seront convertis au format de tableau Markdown.
- Remplacer l'espace réservé : L'espace réservé {{table.person}} dans le fichier tables.md sera remplacé par la table Markdown générée.
? docs/
├── ? img/
├── `architecture.md`
├── `glossary.md`
├── `index.md`
├── `tables.md`
├── ? template/
│ ├── ? db/
│ │ ├── ? data/
│ │ │ ├── hospital.db
│ │ ├── ? queries/
│ ├── `architecture.md`
│ ├── `glossary.md`
│ ├── `index.md`
│ ├── `tables.md`
│ └── `update.py`
? infraestructure/
? github/
├── ? workflows/
│ ├── main.yml
? mkdocs.yml
De cette façon, la documentation reflète toujours des données à jour, affichant des exemples dynamiques basés sur le contenu réel de la base de données.
⚙️ Mkdocs : workflow final
- Créer des modèles : Développez vos pages dans le répertoire docs/template.
- Exécutez update.py : remplissez le contenu dynamique et générez les fichiers finaux dans docs/output.
- Aperçu localement : utilisez le service mkdocs pour prévisualiser le site sur localhost.
- Build for Deployment : utilisez mkdocs build pour générer un site statique dans le dossier docs/.
- Déployer : utilisez Terraform pour déployer le site sur un compartiment AWS S3. Reportez-vous à la section déploiement de cet article pour des instructions détaillées.
? Implémentation du Docusaurus
Dans les sections suivantes, je fournirai des étapes détaillées et des informations sur la façon de mettre en œuvre un site de documentation à l'aide de Docusaurus. Cela inclut les options de configuration, de personnalisation et de déploiement.
? Principales caractéristiques du Docusaurus
- ? Support Mermaid : Semblable à MkDocs, Docusaurus prend en charge Mermaid pour l'intégration de diagrammes.
- ⚛️ Composants React : Construit sur React, Docusaurus permet l'intégration de composants dynamiques dans votre documentation.
- ? Contenu dynamique : exploite les scripts Python pour récupérer et mettre à jour le contenu de manière dynamique à partir d'une base de données SQLite.
? Configuration de Docusaurus : à partir de zéro
Pour démarrer avec Docusaurus, nous suivons un processus de configuration rapide, très similaire aux étapes que nous avons utilisées pour MkDocs mais avec des outils différents.
- Créer un nouveau projet Docusaurus : Tout d'abord, installez Node.js et exécutez la commande suivante pour créer un nouveau site Docusaurus :
pip install mkdocs mkdocs-material
- Installer le package Sirène : Pour activer les diagrammes Mermaid, installez le package requis :
pip install aiosql pandas sqlite3 jinja2 shutil
- Exécutez le serveur de développement : Une fois installé, accédez au répertoire de votre projet et exécutez le serveur de développement :
mkdocs new mkdocs cd mkdocs
- Visitez le site : Votre site sera en ligne localement sur : http://localhost:3000.
? Personnalisation du Docusaurus : configuration
Le fichier de configuration docusaurus.config.js est l'endroit où nous personnalisons le titre, le thème, la navigation et activons des fonctionnalités telles que Mermaid pour le rendu des diagrammes.
Exemple d'extrait pour activer Mermaid :
pip install mkdocs mkdocs-material
? Docusaurus Personnalisation de la page d'accueil
Pour personnaliser la page d'accueil, nous modifions le fichier src/components/HomepageFeatures/index.js. Ici, vous pouvez ajuster l'objet FeatureList pour mettre à jour les fonctionnalités affichées sur la page d'accueil.
? Organisation et structure du contenu Docusaurus
Tout comme dans MkDocs, Docusaurus prend en charge les fichiers Markdown pour le contenu, et nous organisons la structure comme suit :
- Dossier de modèles : stockez vos fichiers Markdown dans le répertoire docs/template et créez un script Python (similaire à update.py) pour récupérer et remplir des données dynamiques dans ces modèles.
- Fichier de catégorie (__category__.json) : Pour gérer l'ordre des documents dans la barre latérale, créez un fichier __category__.json dans chaque dossier. Par exemple:
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json Exemple :
mkdocs new mkdocs cd mkdocs
⚙️ Données dynamiques avec Jinja
Pour incorporer du contenu dynamique, tel que des tables de base de données, nous utilisons un script ?Python nommé update.py, que vous pouvez trouver dans le référentiel.
Ce script récupère les données d'une base de données SQLite et traite les fichiers Markdown stockés dans le dossier des modèles. Il met ensuite à jour ces fichiers avec les données récupérées et les copie dans le dossier docs, les préparant pour le rendu du site.
Ce workflow garantit que le contenu reste à jour et prêt à être déployé, suivant une approche similaire à celle que nous avons implémentée avec MkDocs.
⚙️ Docusaurus : flux de travail final
- Créer des modèles : Développez vos fichiers Markdown dans le répertoire docs/template.
- Exécuter le script Python : utilisez le script pour remplir dynamiquement les données dans les modèles.
- Aperçu localement : exécutez npx docusaurus start pour prévisualiser le site.
- Build for Deployment : Une fois prêt, utilisez npx docusaurus build pour générer le site statique.
- Déployer : hébergez les fichiers statiques sur votre plateforme préférée, telle qu'AWS S3.
? Déploiement
Dans cette section, nous aborderons le processus de déploiement pour MkDocs et Docusaurus en utilisant AWS S3 pour l'hébergement. Bien que les étapes de déploiement soient les mêmes pour les deux outils, les processus d'installation diffèrent, MkDocs étant basé sur Python et Docusaurus étant basé sur JavaScript.
Configuration de l'infrastructure avec Terraform
Pour déployer un site de documentation statique sur AWS S3, nous utilisons Terraform pour provisionner et configurer les ressources requises. La configuration définit le compartiment S3, active l'hébergement de sites Web statiques et configure l'accès public avec une stratégie de compartiment pour autoriser l'accès en lecture seule. Vous pouvez trouver le fichier main.tf dans le référentiel.
? Composants clés pour le déploiement de S3
- S3 Bucket Creation : La ressource pour créer le bucket S3 où la documentation sera hébergée.
- Hébergement de site Web statique : Configuration pour l'hébergement Web statique, définissant index.html et error.html comme documents principaux et d'erreur.
- Configuration de l'accès public : gère l'accès public au compartiment S3, en garantissant qu'il est configuré pour un accès en lecture seule.
- Politique du compartiment : autorise l'accès public pour récupérer le contenu de la documentation du compartiment S3.
Vous pouvez accéder au fichier Terraform complet et aux configurations correspondantes pour le déploiement du site dans le référentiel :
Fichier de configuration Terraform :
- fichier mkdocs
- fichier docusaure
GitHub Action Workflow pour le déploiement automatique : un pipeline CI/CD pour automatiser le processus de déploiement est également inclus dans le référentiel.
- fichier mkdocs
- fichier docusaure
Configuration des actions GitHub
Assurez-vous de configurer vos informations d'identification AWS dans les Secrets du référentiel GitHub sous Paramètres > Secrets> Actions. Cela permettra à GitHub Actions d'accéder en toute sécurité à votre compte AWS et d'effectuer des actions telles que le téléchargement de fichiers sur S3 lorsque vous transmettez des modifications à la branche principale.
Dépôts
Vous trouverez ci-dessous les liens vers tout le code pour déployer votre site de documentation. Si vous le trouvez utile, vous pouvez laisser une étoile ⭐️ et me suivre pour recevoir des notifications de nouveaux articles. Cela m'aidera à grandir dans la communauté technologique et à créer plus de contenu.
- Déploiement MkDocs : référentiel GitHub pour MkDocs
r0mymendez
/
doc-as-code-mkdocs
Un tutoriel sur la façon de créer un projet de documentation en utilisant la méthodologie 'Doc as Code'
⚙️ Doc as Code Tutoriel
? MkDocs & MkDocs-matériel
MkDocs est une excellente solution pour mettre en œuvre un portail de documentation qui peut être facilement mis à jour avec du code, aidant ainsi à maintenir la documentation de votre projet de développement logiciel à jour et versionnée.
Dans ce référentiel, j'ai créé un site simple pour documenter le modèle de données et le projet d'apprentissage automatique.
La documentation comprendra des graphiques, des tableaux et des exemples d'architecture, fournissant un guide complet et facile à comprendre sur la façon de mettre en œuvre ce framework en combinaison avec deux autres bibliothèques ?Python.
Qu'est-ce que la documentation en tant que code ?
La documentation et ses mises à jour sont un processus important dans de nombreuses entreprises qui développent des logiciels, où ce processus est effectué à l'aide de différents outils, dont beaucoup sont des solutions payantes.
C'est pourquoi, ces derniers temps, le concept de "doc as code" a émergé. Cela signifie utiliser les mêmes outils et flux de travail que ceux utilisés dans le développement de logiciels pour gérer, versionner et…
- Déploiement de Docusaurus : référentiel GitHub pour Docusaurus
r0mymendez
/
doc-as-code-docusaurus
Un tutoriel sur la façon de créer un projet de documentation en utilisant la méthodologie 'Doc as code'
⚙️ Doc as Code Tutoriel
? Docusaure
Docusaurus est une excellente solution pour mettre en œuvre un portail de documentation qui peut être facilement mis à jour avec du code, aidant ainsi à maintenir la documentation de votre projet de développement logiciel à jour et versionnée.
Dans ce référentiel, j'ai créé un site simple pour documenter le modèle de données et le projet d'apprentissage automatique.
La documentation comprendra des graphiques, des tableaux et des exemples d'architecture, fournissant un guide complet et facile à comprendre sur la façon de mettre en œuvre ce framework en combinaison avec deux autres bibliothèques ?Python.
Qu'est-ce que la documentation en tant que code ?
La documentation et ses mises à jour sont un processus important dans de nombreuses entreprises qui développent des logiciels, où ce processus est effectué à l'aide de différents outils, dont beaucoup sont des solutions payantes.
C'est pourquoi, ces derniers temps, le concept de "doc as code" a émergé. Cela signifie utiliser les mêmes outils et flux de travail que ceux utilisés dans le développement de logiciels pour gérer, versionner et déployer la documentation…
? Conclusions finales : MkDocs contre Docusaurus
Les deux solutions sont faciles à mettre en œuvre, mais dans les éléments suivants, nous pouvons explorer certaines différences, et la meilleure solution dépend du contexte, des connaissances et de la complexité que vous devrez peut-être mettre en œuvre.
- ? Langue et personnalisation : MkDocs est basé sur Python, avec des configurations et des modèles YAML simples, idéal pour des configurations rapides. D'autre part, Docusaurus est basé sur React, offrant une personnalisation avancée et des composants interactifs, ce qui le rend plus adapté aux utilisateurs ayant besoin de plus de contrôle sur les visuels.
- ? Marquage et rendu : Les deux utilisent Markdown, mais Docusaurus permet des éléments interactifs, ce qui le rend meilleur pour le contenu dynamique.
- ⚙️ Complexité : Docusaurus est préférable pour les applications de documentation complexes, telles que celles dotées de systèmes de connexion. MkDocs est plus simple mais Docusaurus offre plus de flexibilité en termes de style et de fonctionnalités.
- ? Communauté : Docusaurus possède une forte communauté avec Discord et 74 plugins, tandis que MkDocs s'appuie sur les discussions GitHub pour le support de la communauté.
- ☁️ Déploiement Amazon : Vous pouvez déployer un site statique sur S3, réduisant ainsi les coûts de déploiement, et également utiliser CI/CD pour un déploiement automatique.
? Références
- Mkdocs : https://www.mkdocs.org/
- Mkdocs-Matériel : https://squidfunk.github.io/mkdocs-material/
- Diagrammes : https://diagrams.mingrammer.com/
- Docusaurus : https://docusaurus.io/
- Jinja : https://jinja.palletsprojects.com/en/stable/
- Git Book - Qu'est-ce que doc as code : https://www.gitbook.com/blog/what-is-docs-as-code
- Rédiger les documents : https://www.writethedocs.org/guide/docs-as-code/
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!