Dans cet article, je vais vous guider étape par étape pour créer une documentation visuelle dynamique et interactive à l'aide des outils Diagram-as-Code. Au lieu d'images statiques, nous générerons des diagrammes par programmation, en veillant à ce qu'ils soient toujours à jour et faciles à maintenir.

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

? Diagramme sous forme de 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.

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

? Représentation des diagrammes sous forme de code : créez et mettez à jour des diagrammes directement à partir du code, garantissant ainsi la maintenabilité dans les projets agiles.
? Documentation automatisée : générez des visuels à partir du code, en gardant les diagrammes alignés sur l'architecture actuelle.
? Change Control : suivez les modifications du diagramme au fil du temps.
? Clarté améliorée : améliorez la compréhension des systèmes complexes avec des visuels clairs et partagés.
✏️ Personnalisable : représentez les infrastructures cloud, les flux de travail ou les pipelines de données avec des visuels flexibles et personnalisés.

Tutoriel

? Installation de la bibliothèque

J'utilisais actuellement la version '0.23.4' pour ce tutoriel.

!pip install diagrams=='0.23.4'

Copier après la connexion

? Diagrammes : nœuds

La bibliothèque vous permet de créer des diagrammes architecturaux par programmation, en utilisant des nœuds pour représenter différents composants et services d'infrastructure.

Types de nœuds

Les nœuds dans les diagrammes représentent des composants de différents fournisseurs de services cloud ainsi que d'autres éléments architecturaux. Voici les principales catégories de nœuds disponibles :

☁️ Fournisseurs de cloud : AWS (Amazon Web Services), Azure, GCP, IBM Cloud, Alibaba Cloud, Oracle Cloud, DigitalOcean, entre autres.
? On-Premise : Représente l'infrastructure physiquement située dans les locaux de l'entreprise.
? Kubernetes (K8S) : Système d'orchestration de conteneurs pour automatiser le déploiement, la mise à l'échelle et la gestion d'applications conteneurisées (représentées par une roue de navire, symbolisant le contrôle et la navigation).
?️ OpenStack : Plateforme logicielle open source pour la création et la gestion de cloud publics et privés.
? Générique : nœuds génériques pouvant représenter tout composant non spécifiquement couvert par les nœuds spécifiques au fournisseur (outils croisés, représentant différents outils dans une même catégorie).
☁️ SaaS (Software as a Service) : Représente les applications fournies en tant que service sur Internet, telles que Snowflake, les services de chat (Slack, Teams, Telegram, entre autres), la sécurité (par exemple, Okta ), ou les réseaux sociaux (téléphone barré et cloud pour le concept SaaS).
? Personnalisé : Permet aux utilisateurs de personnaliser leurs diagrammes à l'aide d'icônes PNG stockées dans un dossier spécifique. Ceci est utile pour représenter les composants d'infrastructure non couverts par les nœuds par défaut (outils personnalisés barrés).

? Langages de programmation

La bibliothèque Diagrammes vous permet d'utiliser différents nœuds pour représenter différents langages de programmation. Ces nœuds sont utiles pour indiquer dans vos diagrammes si une partie de votre architecture utilise des scripts ou des composants développés dans un langage de programmation spécifique.

Ci-dessous, nous présenterons toutes les langues disponibles dans la bibliothèque. Si une langue manque, vous pouvez ajouter des nœuds personnalisés en téléchargeant le logo correspondant dans un dossier spécifique.

!pip install diagrams=='0.23.4'

Copier après la connexion

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

☁️ AWS (Amazon Web Services)

Nous pouvons utiliser les nœuds Amazon, qui sont organisés en plusieurs catégories, telles que :

Analyse et affaires : aws.analytics, aws.business
Calcul et stockage : aws.compute, aws.storage, aws.cost
Base de données et DevTools : aws.database, aws.devtools
Intégration et gestion : aws.integration, aws.management
Apprentissage automatique et mobile : aws.ml, aws.mobile
Réseau et sécurité : aws.network, aws.security
Autres : aws.blockchain, aws.enduser, aws.engagement, aws.game, aws.general, aws.iot, aws.media, aws.migration, aws.quantum, aws.robotics, aws. satellite

Ensuite, nous représenterons l'une de ces catégories pour visualiser les nœuds disponibles dans aws.database.

!pip install diagrams=='0.23.4'

Copier après la connexion

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

☁️ Cas d'utilisation

Créons maintenant un plan simple qui correspond à l'importation d'un ensemble de données et à la formation d'un modèle d'apprentissage automatique sur AWS.

# Create the diagram object
with diagrams.Diagram("Programming Languages", show=False, filename="languages"):
    # Get all the languages available in this library
    languages = [item for item in dir(diagrams.programming.language) if item[0] != '_']

    # Divide the representation in two lines
    mid_index = len(languages) // 2
    first_line = languages[:mid_index]
    second_line = languages[mid_index:]

    # Add nodes in the first row
    prev_node = None

    for language in first_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

    # Add nodes in the second row
    prev_node = None

    for language in second_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("languages.png")

Copier après la connexion

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

Dépôt

Ci-dessous le lien vers tout le code, 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 / 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: Creating Dynamic and Interactive Documentation for Visual Content

? Diagram-as-Code : Création d'une documentation dynamique et interactive pour le contenu visuel

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

Qu'est-ce que les diagrammes ?

? Avantages du diagramme en tant que code

?…

Voir sur GitHub

Si vous souhaitez voir comment implémenter un site de documentation en utilisant ce pipeline vous pouvez lire l'article que j'ai publié dans le lien suivant