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 !
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.
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.
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.
MkDocs Material est un thème avancé pour MkDocs qui suit les directives de conception matérielle de Google.
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.
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.
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.
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.
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
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.
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.
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.
Pour cette raison notre site de documentation comportera les pages suivantes :
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.
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
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
| 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. |
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.
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.
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
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.
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 :
? 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.
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.
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.
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
mkdocs new mkdocs cd mkdocs
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
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.
Tout comme dans MkDocs, Docusaurus prend en charge les fichiers Markdown pour le contenu, et nous organisons la structure comme suit :
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json Exemple :
mkdocs new mkdocs cd mkdocs
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.
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.
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.
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 :
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.
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.
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.
r0mymendez
/
doc-as-code-mkdocs
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.
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…
r0mymendez
/
doc-as-code-docusaurus
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.
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…
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.
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!
Le Bitcoin est-il légal en Chine ?
Utilisation de caractères arbitraires dans les expressions régulières
Paiement sans mot de passe Taobao
Logiciel gratuit de récupération de données
La différence entre mysql et sql_server
Les principaux dangers des virus chevaux de Troie
Cache mybatis de premier niveau et cache de deuxième niveau
Configurer les variables d'environnement Java
![[Web front-end] Démarrage rapide de Node.js](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
