Docs-as-code en action : Documenter une bibliothèque Python.

La documentation est une ressource cruciale pour aider votre public cible à comprendre comment utiliser efficacement votre produit. Une documentation de haute qualité communique non seulement le problème principal résolu par votre produit, mais permet également aux utilisateurs d'atteindre les résultats souhaités de manière transparente.

Il en va de même pour les bibliothèques et les packages open source. Une documentation claire et accessible est essentielle pour guider les développeurs sur la manière d'intégrer avec succès ces outils dans leurs projets.

Ces dernières années, l'approche Docs-as-Code (DaC) de la documentation a gagné en popularité. Cette méthode considère la documentation comme un élément fondamental du cycle de vie du développement logiciel en utilisant les mêmes outils et processus sur lesquels les développeurs s'appuient pour le code.

Cette méthode est largement acceptée car elle favorise une documentation cohérente, contrôlée en version et facilement maintenable qui évolue parallèlement au produit.

Qu'est-ce que Docs-as-Code ?

En termes simples, DaC est une méthode qui implique de gérer et de maintenir la documentation comme vous le feriez pour votre code.

Un cycle de vie typique de développement logiciel comprend 7 étapes, dont les suivantes :

1. Planification
2. Collecte des exigences et analyses
3. Conception
4. Codage et mise en œuvre
5. Test de code
6. Déploiement de code
7. Maintenance des codes

Par conséquent, DaC est une nouvelle approche qui garantit que la documentation passe par les mêmes étapes. Cela permet de maintenir la documentation versionnée et à jour avec les modifications logicielles.

Déploiement sans DaC

Déploiement avec DaC

Bien que ce guide n'approfondisse pas l'aspect théorique de DaC, vous pouvez explorer l'article Guide du débutant sur Docs-as-code qui explique en détail le concept derrière DaC.

Aperçu du projet

Ce guide implique la mise en œuvre pratique de DaC avec Python. Vous apprendrez à documenter une bibliothèque Python open source à l'aide de Mintlify.

Mintlify est un générateur de site statique et un site de documentation utilisé pour la documentation destinée au public. Il est facile à maintenir et à utiliser pour divers besoins de documentation tels que la documentation des développeurs, la documentation des API, etc. Il fonctionne également bien avec la méthodologie DaC.

Ce tutoriel est la suite d'un tutoriel existant sur la façon de créer et de déployer une bibliothèque Python. À l'aide de la méthodologie DaC, vous apprendrez à documenter le tutoriel référencé développé par la bibliothèque Python.

Il est recommandé de terminer le tutoriel précédent avant de continuer. Cependant, vous pouvez continuer si vous disposez d'un projet existant à utiliser pour ce tutoriel.

Exigences du projet

Une connaissance de base de Git et GitHub, comment créer un référentiel Github et comment transmettre votre code vers GitHub est requise. Vous avez également besoin des outils suivants pour ce tutoriel :

• Compte Mintlify : Vous avez besoin d'un compte Mintlify actif pour créer de la documentation (les étapes seront fournies dans le guide).
• Node.js : Vous aurez besoin de Node.js version 18 et supérieure pour installer Mintlify et modifier votre documentation localement.

Configurer une documentation Mintlify

Suivez les étapes ci-dessous pour configurer une documentation à l'aide de Mintlify :

1. Créer un compte sur Mintlify

2. Configurez votre compte Mintlify :
Un lien de vérification sera envoyé à votre courrier. Ce lien vous redirigera vers la page ci-dessous :

3. Connectez-vous avec Github :
La première étape nécessite que vous vous connectiez avec votre compte Github.

4. Créez un dépôt GitHub (repo) pour votre documentation :
L'étape suivante vous oblige à installer et autoriser l'application Mintlify sur votre compte Github. Cela permet à Mintlify de créer automatiquement un dépôt pour vos documents

5. Accédez à votre dépôt de documentation :
L'étape précédente crée un nouveau dépôt de documents pour votre documentation. Vérifiez vos référentiels GitHub pour un nouveau dépôt de documents

Ajoutez la documentation à votre projet

L'étape suivante consiste à cloner le dépôt docs dans votre environnement local et à l'ajouter à un projet existant tel qu'un outil de développement, un package open source, etc. Si vous avez déjà terminé le didacticiel précédent, votre projet sera ExchangeLibrary.

Suivez les étapes ci-dessous pour ajouter la documentation à votre projet :

1. Ouvrez le terminal et clonez le référentiel de documents avec la commande ci-dessous :

git clone https://github.com/<your github username>/docs 

2. Copiez le dossier Docs cloné dans votre projet.

3. Ouvrez le projet dans un éditeur de code.

La structure de vos fichiers de projet devrait maintenant ressembler à ceci :

Prévisualiser la documentation localement

Mintlify vous permet de prévisualiser votre documentation localement avant de la publier. Suivez les étapes ci-dessous pour le configurer :
1. Ouvrez votre projet dans le terminal
2. Exécutez la commande ci-dessous pour installer Mintlify globalement :

git clone https://github.com/<your github username>/docs 

3. Basculez vers le dossier docs de votre projet :

npm i -g mintlify

4. Démarrez un serveur mintlify avec la commande ci-dessous :

cd docs

Vous devriez voir un message comme celui ci-dessous dans votre terminal :

Ouvrez l'URL pour prévisualiser la documentation localement. Le contenu de votre documentation sera le modèle de document de démarrage Mintlify. Cela changera lorsque vous commencerez à modifier votre documentation.

Rédaction du dossier

Une documentation Mintlify est alimentée par le fichier mint.json. Ce fichier contient le jeu de couleurs, la pagination et les paramètres de navigation de la documentation. Vous pouvez le trouver dans le dossier docs du projet.

De plus, les fichiers de documentation dans Mintlify sont écrits en .mdx. Il est presque similaire à markdown (.md), sauf qu'il autorise des balises et des symboles spéciaux.

Dans cette section, vous apprendrez comment modifier les paramètres de votre documentation dans le fichier mint.json et comment ajouter des textes et des composants spéciaux à votre documentation.

Modifier les paramètres de la documentation

Le fichier mint.json est un objet JSON composé de jeux de couleurs, de pagination, de paramètres de navigation, etc. pour votre documentation. Vous trouverez ci-dessous une liste des paramètres disponibles et leur signification :

1. Palette de couleurs et apparence :
Cette section est utilisée pour embellir et améliorer l’apparence de votre documentation. Il est utilisé pour modifier le logo (pour les modes clair et sombre), le favicon, le titre et la palette de couleurs de la documentation. Cela commence à partir de la clé $schema jusqu'à la clé couleurs comme indiqué ci-dessous :

mintlify dev

2. Liens de navigation et bouton CTA :
Cette section est utilisée pour configurer les liens et boutons de navigation en haut de la page de documentation. Vous trouverez ci-dessous un exemple de lien et de bouton de navigation :

Le code ci-dessous configure les liens de navigation et un bouton CTA pour votre documentation Mintlify :

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

3. Onglets et ancres :
Les onglets et les ancres peuvent être utilisés pour configurer respectivement des sections horizontales et verticales dans votre documentation. Vous trouverez ci-dessous des exemples d'onglets :

Ci-dessous un exemple d'ancre :

Les paramètres de ces composants sont gérés par les touches d'onglets et d'ancrage.

4. Paramètres de navigation :
Cette section vous aide à regrouper les pages de votre documentation. Il s'agit d'un tableau composé d'une clé de groupe et d'un tableau de pages dans lequel les pages du groupe sont ajoutées séquentiellement. Vous trouverez ci-dessous un exemple de la façon dont il est ajouté :

git clone https://github.com/<your github username>/docs 

Les paramètres ci-dessus se traduiront par l'image ci-dessous :

Les pages (introduction, etc.) sont des fichiers .mdx dans le dossier docs de votre projet.

5. Navigation imbriquée :
La navigation imbriquée est couramment utilisée pour créer des sous-sections dans une documentation. Ci-dessous un exemple de navigation imbriquée :

Vous trouverez ci-dessous un exemple de code pour mettre en place une navigation imbriquée sur Mintlify :

npm i -g mintlify

Le code ci-dessus imbrique une section/un groupe dans une autre section. La touche icône embellit le titre de la section avec une icône lorsqu'elle est affichée sur une page Web.

6. Paramètres du pied de page :
La clé footerSocials est utilisée pour ajouter des comptes de réseaux sociaux liés à la documentation. Ci-dessous un exemple :

Comment ajouter du contenu

La documentation Mintlify vous guide sur la façon d'ajouter du contenu à votre documentation. Je vous recommande de consulter la documentation pour savoir comment ajouter du contenu différent à votre documentation.

Consultez cet exemple de documentation pour vous inspirer sur la manière de structurer votre propre documentation.

Conseils pour la rédaction de documents

Voici quelques conseils pour vous aider à rédiger une documentation claire et conviviale :

1. Soyez aussi direct que possible : Évitez les informations superflues qui n’ajoutent aucune valeur. Votre documentation est destinée aux développeurs qui souhaitent utiliser votre package ou outil dans leur prochain projet, montrez-leur donc uniquement ce dont ils ont besoin pour y parvenir.

2. Ajoutez une description ou un aperçu de votre outil :
Avant d'entrer dans les détails sur la façon d'utiliser votre outil, décrivez brièvement ce qu'est votre outil et le problème qu'il résout. Cela devrait être sur la première page.

3. Ajoutez suffisamment d'échantillons de code :
Cela les aidera à comprendre comment utiliser votre outil sans erreurs inutiles. Les exemples de code sur l'installation, l'authentification, les exemples de réponses, les arguments de méthode, etc. sont très importants.

4. Erreurs et exceptions :
Cela aidera les utilisateurs dans le débogage. Ajoutez une page pour décrire le type d'erreurs que les utilisateurs peuvent rencontrer lors de l'utilisation de votre outil. Affichez également des exemples de code pour cela.

Pousser le projet vers Github

Suivez les étapes ci-dessous pour pousser le projet vers Github :

1. Ouvrez un terminal git bash dans votre projet et basculez dans le dossier docs avec la commande ci-dessous :

git clone https://github.com/<your github username>/docs 

2. Supprimez git de ce dossier avec la commande ci-dessous :

npm i -g mintlify

Cette commande supprime .git du dossier docs pour éviter les problèmes lorsque vous souhaitez transférer l'intégralité du projet vers Github.

3. Poussez le projet sur GitHub.

Déployer la documentation

Suivez les étapes ci-dessous pour déployer votre documentation sur Mintlify :
1. Connectez-vous à votre tableau de bord Mintlify
2. Cliquez sur l'onglet Paramètres

3. Remplacez votre dépôt Mintlify Github par le dépôt de votre projet

4. Activez le commutateur monorepo. Cela signifie que le dossier docs existe dans un autre projet dans un seul dépôt.

5. Entrez **docs comme chemin d'accès au fichier mint.json dans le nouveau champ qui apparaît.**

6. Cliquez sur le bouton Enregistrer pour enregistrer les modifications.

Votre documentation est accessible via le lien affiché dans l'onglet aperçu de votre tableau de bord

Mise à jour du projet

Vous êtes très susceptible d’apporter des modifications à votre projet et devrez peut-être le redéployer.

Après avoir effectué des mises à jour dans votre projet, assurez-vous de transmettre les modifications à Github. Mintlify récupère automatiquement les nouvelles modifications et met à jour vos documents rapidement.

Conclusion

Dans ce didacticiel, vous avez appris à créer de la documentation pour une bibliothèque Python en utilisant l'approche docs-as-code.

Docs-as-code favorise la collaboration et l'intégration continue sur un projet. Lorsqu'il s'agit d'open source, docs-as-code permet aux utilisateurs de collaborer de manière transparente sur un projet tout en conservant une documentation appropriée et à jour.

Il existe différentes API REST sans SDK ni bibliothèques de programmation. Sélectionnez-en un qui vous intéresse et créez quelque chose de similaire.

Continuer à construire ?‍?!

FAQ

Comment tester ma documentation ?

Cette fonctionnalité est souvent utilisée sur les grands projets avec plusieurs contributeurs. Les tests de documentation sont exécutés automatiquement lorsqu'une pull request est adressée au projet. Si le test réussit, les modifications sont fusionnées. Lisez ce guide sur la façon dont swimm propose des tests de documentation automatiques pour en savoir plus.

Puis-je reproduire ce projet dans d'autres langages de programmation ?
Oui, vous pouvez. Suivez les procédures de ce guide pour obtenir un résultat similaire dans votre langue préférée.

Existe-t-il d'autres sites de documentation à part Mintlify ?
Oui, il existe d'autres sites de documentation que vous pouvez utiliser. Certains d'entre eux incluent : Gitbook, Readme, Docusaurus, etc.

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!