| Les deux révisions précédentes Révision précédente Prochaine révision | Révision précédente |
| outils:docfx [2021/08/11 18:52] – phil | outils:docfx [2023/08/19 12:15] (Version actuelle) – phil |
|---|
| |
| ===== Outils - Mise en oeuvre de DocFX ===== | ===== Outils - Mise en oeuvre de DocFX ===== |
| [Mise à jour le 2/2/2019] | [Mise à jour le 18/8/2023] |
| |
| * **Source** | * **Source** |
| * Cet article a été écrit à partir de la documentation du site <html><a href="https://dotnet.github.io/docfx/" target="_blank"><strong>DocFx</strong></a></html> | * Cet article a été écrit à partir de la documentation du site <html><a href="https://dotnet.github.io/docfx/" target="_blank"><strong>DocFx</strong></a></html> |
| <note important>Lors d'une première lecture, les différentes parties doivent être abordées dans l'ordre.</note> | <callout type="warning" icon="true">Les différentes parties doivent être abordées dans l'ordre en première lecture.</callout> |
| |
| ==== A. Qu'est-ce que DocFX ? ==== | ==== A. Qu'est-ce que DocFX ? ==== |
| Nous allons nous familiariser avec le principe général d'organisation des documents dans docFX pour générer un site statique. | Nous allons nous familiariser avec le principe général d'organisation des documents dans docFX pour générer un site statique. |
| |
| * **Étape 1. Configurer DocFX** | * **Étape 1. Configurer DocFX** \\ Il y a [[https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-exe-directly|trois manières]] d'installer DocFX. Dans ce qui suit, nous utilisons directement l'exécutable //**docfx.exe**//. |
| Il y a [[https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-exe-directly|trois manières]] d'installer DocFX. Dans ce qui suit, nous utilisons directement l'exécutable //**docfx.exe**//. | - Télécharger [[https://github.com/dotnet/docfx/releases|docfx.zip]] et le dézipper dans D:\docfx\ |
| - Télécharger [[https://github.com/dotnet/docfx/releases|docfx.zip]] et le dézipper dans D:\docfx\ | - Sous Windows, ajouter le chemin D:\docfx\ aux variables d'environnement (PATH) pour que la commande docfx soit accessible dans tous les dossiers. |
| - Sous Windows, ajouter le chemin D:\docfx\ aux variables d'environnement (PATH) pour que la commande docfx soit accessible dans tous les dossiers. | |
| |
| * ** Étape 2. Initier un projet DocFX** | * ** Étape 2. Initier un projet DocFX** \\ |
| - Créer un nouveau répertoire. Par exemple //D:\docfx_pasapas//. | - Créer un nouveau répertoire. Par exemple //D:\docfx_pasapas//. |
| - Ouvrir la ligne de commande dans ce nouveau dossier. | - Ouvrir la ligne de commande dans ce nouveau dossier. |
| - Exécuter la commande **''docfx init -q''**. Cette commande génère un dossier //docfx_project// contenant le fichier //**docfx.json**// par défaut. docfx.json est le fichier de configuration que docfx utilise pour générer la documentation. | - Exécuter la commande **''docfx init -q''**. Cette commande génère un dossier //docfx_project// contenant le fichier //**docfx.json**// par défaut. docfx.json est le fichier de configuration que docfx utilise pour générer la documentation. |
| {{ :outils:lignecmd.png?nolink |}} | {{ :outils:lignecmd.png?nolink |}} |
| |
| <note tip>L'option **-q** signifie que le projet est généré en utilisant les valeurs par défaut, vous pouvez également essayer docfx init et suivre les instructions pour fournir vos propres paramètres.</note> | <callout type="tip" icon="true">L'option **-q** signifie que le projet est généré en utilisant les valeurs par défaut, vous pouvez également essayer docfx init et suivre les instructions pour fournir vos propres paramètres.</callout> |
| |
| * **Étape 3. Construire le site Web** | * **Étape 3. Construire le site Web** \\ Exécuter la commande ''**docfx** //docfx_project/docfx.json//''. Notez qu'un nouveau sous-dossier **_site** est généré dans ce dossier. C'est là que le site Web statique est généré. |
| Exécuter la commande ''**docfx** //docfx_project/docfx.json//''. Notez qu'un nouveau sous-dossier **_site** est généré dans ce dossier. C'est là que le site Web statique est généré. | |
| |
| * **Étape 4. Prévisualiser le site Web** | * **Étape 4. Prévisualiser le site Web** \\ Le site Web statique généré peut être publié sur les pages **GitHub**, sur les sites Web Azure ou sur vos propres services d'hébergement, sans aucune modification supplémentaire. Vous pouvez également exécuter la commande ''**docfx serve** //docfx_project/_site//'' pour prévisualiser le site Web localement. |
| Le site Web statique généré peut être publié sur les pages **GitHub**, sur les sites Web Azure ou sur vos propres services d'hébergement, sans aucune modification supplémentaire. Vous pouvez également exécuter la commande ''**docfx serve** //docfx_project/_site//'' pour prévisualiser le site Web localement. | |
| |
| <note warning>Si le port **8080** n'est pas utilisé, docfx hébergera //_site// sous **http://localhost:8080**. Si 8080 est utilisé, vous pouvez utiliser ''**docfx serve** _site **-p** <port>'' pour changer le port.</note> | <callout type="warning" color="red" icon="true">Si le port **8080** n'est pas utilisé, docfx hébergera //_site_// sous **http://localhost:8080**. Si 8080 est utilisé, vous pouvez utiliser ''**docfx serve** _site **-p** <port>'' pour changer le port.</callout> \\ La page devrait ressembler à ceci. {{ :outils:walkthrough_simple_homepage.png?nolink&600 |}} |
| |
| La page devrait ressembler à ceci. | * **Étape 5. Ajouter des articles au site Web** \\ **1.** Pour ajouter des articles au site, il suffit de placer des fichiers au format markdown **.md** dans le sous-dossier //**articles**//. Ajoutons par exemple les fichiers //details1.md//, //details2.md//, //details3.md//. Si les fichiers font référence à des ressources, placez-les dans le dossier images. \\ **2.** Afin d'organiser ces articles, ajoutons des références à ces fichiers dans le fichier //**toc.yml**// contenu dans le sous-répertoire **//articles//**. Le contenu de //toc.yml// doit être complété comme ci-dessous: <code yaml> |
| {{ :outils:walkthrough_simple_homepage.png?nolink&600 |}} | |
| | |
| * **Étape 5. Ajouter des articles au site Web** | |
| **1.** Pour ajouter des articles au site, il suffit de placer des fichiers au format markdown **.md** dans le sous-dossier //**articles**//. Ajoutons par exemple les fichiers //details1.md//, //details2.md//, //details3.md//. Si les fichiers font référence à des ressources, placez-les dans le dossier images. | |
| | |
| **2.** Afin d'organiser ces articles, ajoutons des références à ces fichiers dans le fichier //**toc.yml**// contenu dans le sous-répertoire **//articles//**. Le contenu de //toc.yml// doit être complété comme ci-dessous: | |
| <code yaml> | |
| - name: Introduction | - name: Introduction |
| href: intro.md | href: intro.md |
| - name: Details 3 | - name: Details 3 |
| href: details3.md | href: details3.md |
| | </code> \\ L'organisation des dossiers est maintenant : \\ <code yaml> |
| </code> | |
| L'organisation des dossiers est maintenant : | |
| | |
| <code yaml> | |
| |- index.md | |- index.md |
| |- toc.yml | |- toc.yml |
| |- images | |- images |
| |- details1_image.png | |- details1_image.png |
| </code> | </code> \\ **3.** Exécuter à nouveau les commandes des étapes 3 et 4 puis **cliquer** sur **//Article//** pour que le site ressemble à ceci : {{ :outils:walkthrough_step5.png?nolink&600 |}} |
| | |
| **3.** Exécuter à nouveau les commandes des étapes 3 et 4 puis **cliquer** sur **//Article//** pour que le site ressemble à ceci : | |
| | |
| {{ :outils:walkthrough_step5.png?nolink&600 |}} | |
| |
| === Conclusion === | === Conclusion === |
| Dans cette partie, nous allons apprendre à créer un site Web à partir du code source d'un projet .NET, il s'agit de la **Documentation de l'API**. Nous allons également intégrer la documentation conceptuelle et la documentation de l'API dans un site Web unique, de manière à pouvoir naviguer de "Conceptuel" à "API", ou d'"API" à "Conceptuel". | Dans cette partie, nous allons apprendre à créer un site Web à partir du code source d'un projet .NET, il s'agit de la **Documentation de l'API**. Nous allons également intégrer la documentation conceptuelle et la documentation de l'API dans un site Web unique, de manière à pouvoir naviguer de "Conceptuel" à "API", ou d'"API" à "Conceptuel". |
| |
| * **Étape 1. Ajouter un projet C#** | * **Étape 1. Ajouter un projet C#** {{ :outils:vscom2017.jpg?nolink&200|}} |
| {{ :outils:vscom2017.jpg?nolink&200|}} | - Créer un sous-dossier //**src**// sous D:\docfx_pasapas\docfx_project. |
| - Créer un sous-dossier //**src**// sous D:\docfx_pasapas\docfx_project. | - Ouvrir **Visual Studio Community** 2015 (ou une version supérieure) et créer, dans le dossier //src//, une bibliothèque de classes C# que vous nommerez //**HelloDocfx**// . |
| - Ouvrir **Visual Studio Community** 2015 (ou une version supérieure) et créer, dans le dossier //src//, une bibliothèque de classes C# que vous nommerez //**HelloDocfx**// . | - Remplacer le contenu du fichier //Class1.cs//, par celui du fichier téléchargeable [[https://webge.fr/doc/wikis/code/docfx/Class1.zip|ici]]. |
| - Remplacer le contenu du fichier //Class1.cs//, par celui du fichier téléchargeable [[https://webge.fr/doc/wikis/code/docfx/Class1.zip|ici]]. | |
| |
| * **Étape 2. Générer les métadonnées du projet C#** | * **Étape 2. Générer les métadonnées du projet C#** |
| - Se placer dans le dossier //docfx_project// | - Se placer dans le dossier //docfx_project// |
| - Exécuter la commande ''**docfx metadata**'' dans le dossier **D:\docfx_pasapas\docfx_project**. La commande ''docfx metadata'' lit la configuration dans la section metadata du fichier //docfx.json//. La partie <nowiki>[ "src/**.csproj" ]</nowiki> située dans //metadata/src/files// demande à docFX de rechercher tous les //csproj// du sous-dossier //src// pour générer les métadonnées. | - Exécuter la commande ''**docfx metadata**'' dans le dossier **D:\docfx_pasapas\docfx_project**. La commande ''docfx metadata'' lit la configuration dans la section metadata du fichier //docfx.json//. La partie <nowiki>[ "src/**.csproj" ]</nowiki> située dans //metadata/src/files// demande à docFX de rechercher tous les //csproj// du sous-dossier //src// pour générer les métadonnées. |
| |
| <code javascript> | <code javascript> |
| </code> | </code> |
| |
| <note>Notez également que si vos csproj sont situés en dehors de votre répertoire docFX et que vous devez utiliser ../, vous devrez compléter la propriété src.</note> | <callout type="info" icon="true">Notez également que si vos csproj sont situés en dehors de votre répertoire docFX et que vous devez utiliser ../, vous devrez compléter la propriété src.</callout> |
| |
| <code javascript> | <code javascript> |
| |
| * **Étape 4. Ajouter une autre documentation d'API** | * **Étape 4. Ajouter une autre documentation d'API** |
| - Créer un autre sous-dossier **//src2//** sous D:\docfx_pasapas\docfx_project. Outre la génération de documentation API à partir de fichiers de projet, docFX peut générer de la documentation directement à partir du code source. | - Créer un autre sous-dossier **//src2//** sous D:\docfx_pasapas\docfx_project. Outre la génération de documentation API à partir de fichiers de projet, docFX peut générer de la documentation directement à partir du code source. |
| - Télécharger le fichier [[https://webge.fr/doc/wikis/code/docfx/Class2.zip|Class2.cs]], le dézipper et le placer dans //src2// | - Télécharger le fichier [[https://webge.fr/doc/wikis/code/docfx/Class2.zip|Class2.cs]], le dézipper et le placer dans //src2// |
| - Compléter la section //metadata// du fichier //docfx.json// comme ci-dessous :<code JavaScript> | - Compléter la section //metadata// du fichier //docfx.json// comme ci-dessous :<code JavaScript> |
| "metadata": [ | "metadata": [ |
| { | { |
| ], | ], |
| </code> | </code> |
| - Cela signifie que les fichiers de métadonnées YAML pour <nowiki>"src2/**.cs"</nowiki> sont générés dans le dossier "api-vb". Incluons également les fichiers YAML générés dans la section build :<code javascript> | - Cela signifie que les fichiers de métadonnées YAML pour <nowiki>"src2/**.cs"</nowiki> sont générés dans le dossier "api-vb". Incluons également les fichiers YAML générés dans la section build :<code javascript> |
| "build": { | "build": { |
| "content": [ | "content": [ |
| ... | ... |
| </code> | </code> |
| - Pour qu'il soit organisé et affiché sur le site Web, nous devons également modifier le fichier D:\ docfx_walkthrough\docfx_project\**toc.yml**. Ne pas oublier d'ajouter une barre oblique **/** pour la valeur de **href**.:<code yaml> | - Pour qu'il soit organisé et affiché sur le site Web, nous devons également modifier le fichier D:\ docfx_walkthrough\docfx_project\**toc.yml**. Ne pas oublier d'ajouter une barre oblique **/** pour la valeur de **href**.:<code yaml> |
| - name: Articles | - name: Articles |
| href: articles/ | href: articles/ |
| href: api-vb/ | href: api-vb/ |
| </code> | </code> |
| - Exécuter la commande ''**docfx - -serve**'' puis **cliquer** sur **Another Api Documentation**. Le site devrait ressembler à : | - Exécuter la commande ''**docfx - -serve**'' puis **cliquer** sur **Another Api Documentation**. Le site devrait ressembler à : |
| {{ :outils:walkthrough2_step4.png?nolink |}} | {{ :outils:walkthrough2_step4.png?nolink |}} |
| |
| * **Étape 5. Combinez les informations conceptuelles et de référence dans la barre de navigation gauche** | * **Étape 5. Combinez les informations conceptuelles et de référence dans la barre de navigation gauche** \\ La barre de **navigation de gauche** peut contenir des liens vers des **informations conceptuelles** (vue d'ensemble, démarrage, etc.) et des **informations de référence**. |
| La barre de **navigation de gauche** peut contenir des liens vers des **informations conceptuelles** (vue d'ensemble, démarrage, etc.) et des **informations de référence**. | - Remplacer le contenu du fichier **toc.yml**, à la racine, par le texte ci-dessous. (Il détermine le contenu de la barre de menus horizontale principale.)<code yaml> |
| - Remplacer le contenu du fichier **toc.yml**, à la racine, par le texte ci-dessous. (Il détermine le contenu de la barre de menus horizontale principale.)<code yaml> | |
| - name: Home | - name: Home |
| href: index.md | href: index.md |
| href: restapi/ | href: restapi/ |
| </code> | </code> |
| - Ajouter un nouveau dossier à la racine (par exemple, **fusion**). | - Ajouter un nouveau dossier à la racine (par exemple, **fusion**). |
| - À l'intérieur de fusion, ajoutez **//toc.yml//** et dans //toc.yml//, ajouter le texte ci-dessous: <code yaml> | - À l'intérieur de fusion, ajoutez **//toc.yml//** et dans //toc.yml//, ajouter le texte ci-dessous: <code yaml> |
| - name: Conceptual | - name: Conceptual |
| href: ../articles/toc.yml | href: ../articles/toc.yml |
| href: ../obj/api/toc.yml | href: ../obj/api/toc.yml |
| </code> | </code> |
| - Dans le fichier //toc.yml// à la racine, remplacez ../obj/api/toc.yml par le chemin vers fusion : <code yaml> | - Dans le fichier //toc.yml// à la racine, remplacez ../obj/api/toc.yml par le chemin vers fusion : <code yaml> |
| - name: Home | - name: Home |
| href: index.md | href: index.md |
| href: restapi/ | href: restapi/ |
| </code> | </code> |
| - Exécuter la commande ''**docfx - -serve**'' puis cliquer sur **Api Documentation**. Le site devrait ressembler à : | - Exécuter la commande ''**docfx - -serve**'' puis cliquer sur **Api Documentation**. Le site devrait ressembler à : |
| {{ :outils:walkthrough2_step5.png?nolink |}} | {{ :outils:walkthrough2_step5.png?nolink |}} |
| |
phil