Différences

Ci-dessous, les différences entre deux révisions de la page.

--- outils:docfx [2021/08/11 09:19] – modification externe 127.0.0.1
+++ outils:docfx [2023/08/19 12:15] (Version actuelle) – phil
@@ Ligne 1: / Ligne 1: @@
-{{ :suivant.png?nolink&30|}} {{ :retour.png?nolink&30|}} [[outils:accueiloutils|{{ :iconemaison.jpg?nolink&30|Sommaire TinyCLR}}]]
+[[outils:accueiloutils|{{ :iconemaison.jpg?nolink&25|Page outils}}]]
-====== Mise en oeuvre de DocFX======
+===== Outils - Mise en oeuvre de DocFX =====
-[Mise à jour le 2/2/2019]
+[Mise à jour le 18/8/2023]
-{{  :outils:docfx.png?nolink|}}
-=== 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>
-> Lors d'une première lecture, les différentes parties doivent être abordées dans l'ordre.
+<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 ? ====
 DocFX est un **générateur de documentation API pour .NET**, qui prend actuellement en charge C# et VB. Il génère une documentation de référence API à partir de commentaires triples dans votre code source. Il vous permet également d'utiliser des fichiers **Markdown**(([[https://fr.wikipedia.org/wiki/Markdown|Markdown]] est un langage de balisage léger créé en 2004 par John Gruber avec Aaron Swartz. Son but est d'offrir une syntaxe facile à lire et à écrire.)) pour créer des rubriques supplémentaires telles que des didacticiels et des procédures, et de personnaliser la documentation de référence générée. DocFX crée un site Web HTML statique à partir de votre code source et de vos fichiers Markdown, qui peut être facilement hébergé sur tous les serveurs Web (par exemple, **github.io**). De plus, DocFX vous permet de personnaliser la présentation et le style de votre site Web à l'aide de modèles. Si vous souhaitez créer votre propre site Web avec vos propres styles, vous pouvez suivre la procédure de création d’un modèle personnalisé.
-=====B. DocFX étape par étape =====
+==== B. DocFX étape par étape ====
-====1. Générer un site Web de documentation ====
+=== 1. Générer un site Web de documentation ===
 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 |}}
-> 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.
-=== Étape 3. Construire le site Web ===
+<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>
-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 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é.
-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.
-> 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.
+  * **É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.
-La page devrait ressembler à ceci.
+<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 |}}
-{{ :outils:walkthrough_simple_homepage.png?nolink&600 |}}
-=== Étape 5. Ajouter des articles au site Web ===
+  * **É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>
-**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
   href: intro.md
@@ Ligne 53: / Ligne 43: @@
 - name: Details 3
   href: details3.md
-</code>
+</code> \\ L'organisation des dossiers est maintenant : \\ <code yaml>
-L'organisation des dossiers est maintenant :
-<code yaml>
 |- index.md
 |- toc.yml
@@ Ligne 67: / Ligne 54: @@
 |- images
     |- 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 ===
-----
 Dans cette procédure, nous avons construit un site Web à partir d’un ensemble de fichiers markdown. Ces fichiers .md sont la **documentation conceptuelle**. Dans le paragraphe suivant, nous allons apprendre à ajouter la documentation d'une API (([[https://fr.wikipedia.org/wiki/Interface_de_programmation|API : Application Programming Interface]])) à notre site Web. La documentation de l'API sera automatiquement extraite du code source .NET(([[https://fr.wikipedia.org/wiki/Microsoft_.NET|Microsoft .NET]])). Dans une série de procédures avancées, nous verrons d'autres concepts de docFX, tels que les références croisées entre articles, les références externes à d’autres documentations, etc.
 ----
-==== 2. Ajouter la documentation d'une API ====
+=== 2. Ajouter la documentation d'une API ===
 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>
@@ Ligne 110: / Ligne 92: @@
   ]
 </code>
 Cela génère plusieurs fichiers **YAML**(([[https://fr.wikipedia.org/wiki/YAML|YAML]], Acronyme de Yet Another Markup Language dans sa version 1.0, il devient l'acronyme récursif de YAML Ain't Markup Language (« YAML n'est pas un langage de balisage ») dans sa version 1.1, est un format de représentation de données par sérialisation Unicode.)) dans le dossier **//api//**. Un fichier YAML contient le modèle de données extrait du fichier de code source C#. YAML est le format de métadonnées utilisé dans docFX. La spécification de métadonnées générales définit le schéma général et la spécification de métadonnées .NET définit le schéma de métadonnées pour les langages .NET pouvant être consommés par docFX.
@@ Ligne 119: / Ligne 102: @@
 </code>
-> 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 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>
@@ Ligne 142: / Ligne 125: @@
 </code>
-=== Étape 3. Construire et prévisualiser le site===
+  * **Étape 3. Construire et prévisualiser le site**
 Lancer la commande ''**docfx**''. Cette commande lit le fichier //docfx.json// et exécute,  une par une, les sous-commandes. Notre fichier //docfx.json// définit les ''metadata'' et le'' build''. En exécutant la commande docfx, nous construisons le site Web.
@@ Ligne 149: / Ligne 132: @@
 {{ :outils:walkthrough2_step3.png?nolink&800 |}}
-=== É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": [
     {
@@ Ligne 172: / Ligne 155: @@
   ],
 </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": {
     "content": [
@@ Ligne 182: / Ligne 165: @@
       ...
 </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
   href: articles/
@@ Ligne 191: / Ligne 174: @@
   href: api-vb/
 </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 |}}
-=== É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
   href: index.md
@@ Ligne 207: / Ligne 189: @@
   href: restapi/
 </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
   href: ../articles/toc.yml
@@ Ligne 214: / Ligne 196: @@
   href: ../obj/api/toc.yml
 </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
   href: index.md
@@ Ligne 225: / Ligne 207: @@
   href: restapi/
 </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 |}}
-====3. Générer la documentation au format pdf ====
+=== 3. Générer la documentation au format pdf ===
 A l'étape précédente, nous avons créé un site Web contenant à la fois la documentation conceptuelle et la documentation API. Dans cette partie, nous allons générer cette documentation au format PDF.
@@ Ligne 243: / Ligne 225: @@
 </code>
-===Étape 0. Installer les prérequis===
+  * **Étape 0. Installer les prérequis**
 Nous utiliserons [[https://wkhtmltopdf.org/|wkhtmltopdf]]((wkhtmltopdf est un outil en ligne de commande open source (LGPLv3) pour le rendu HTML en PDF)) pour générer des PDF. Télécharger l'exécutable wkhtmltopdf et l'installer.
-===Étape 1. Ajouter un fichier toc.yml spécifique aux PDF===
+  * **Étape 1. Ajouter un fichier toc.yml spécifique aux PDF**
 Chaque fichier TOC génère le fichier PDF correspondant, TOC est également utilisé pour la page de couverture du PDF, nous créons donc un fichier toc.yml spécifique au PDF dans un nouveau dossier pdf, en utilisant [[http://dotnet.github.io/docfx/tutorial/intro_toc.html?q=toc%20inclu#link-to-another-toc-file|TOC Include]] pour inclure le contenu d'autres fichiers TOC.
 <code yaml>
@@ Ligne 257: / Ligne 239: @@
 </code>
-===Étape 2. Ajouter une section pdf dans docfx.json===
+  * **Étape 2. Ajouter une section pdf dans docfx.json**
 Les paramètres ressemblent à ceux de la section "construction", bien qu'on utilise un modèle différent (le modèle intégré est pdf.default), avec une autre destination. Nous excluons les fichiers TOC car chaque fichier TOC génère un fichier PDF:
 <code JavaScript>
@@ Ligne 323: / Ligne 305: @@
 {{ :outils:walkthrough3.png?nolink&600 |}}
-===Etape 3 facultative. Activer les plugins===
+  * **Etape 3 facultative. Activer les plugins**
 Si vous souhaitez également utiliser des plugins avec pdf, vous devez ajouter un noeud de modèle à la section pdf. Il doit commencer par le fichier pdf.template suivi du chemin d'accès aux plugins que vous souhaitez utiliser :
 <code javascript>
@@ Ligne 332: / Ligne 314: @@
  </code>
-==== 4. Personnaliser son site ====
+  * **4. Personnaliser son site**
 Voir la page consacrée à cette rubrique [[https://dotnet.github.io/docfx/tutorial/walkthrough/advanced_walkthrough.html|ici]].