Table des matières

Page outils

Outils - Mise en oeuvre de DocFX

[Mise à jour le 18/8/2023]

Les différentes parties doivent être abordées dans l'ordre en première lecture.

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 Markdown1) 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

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.

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.
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.


La page devrait ressembler à ceci.

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 2) à notre site Web. La documentation de l'API sera automatiquement extraite du code source .NET3). 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

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”. 

"metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ],
          "exclude": [
            "**/bin/**",
            "**/obj/**",
            "_site/**"
          ]
        }
      ],
      "dest": "api"
    }
  ]

Cela génère plusieurs fichiers YAML4) 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. 

|- HelloDocfx.Class1.InnerClass.yml
|- HelloDocfx.Class1.yml
|- HelloDocfx.yml
|- toc.yml
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.
"metadata": [
    {
      "src": [
        {
          "src": "../../",
          "files": [
            "somewhere/src/**.csproj"
          ],
          "exclude": [
            "**/bin/**",
            "**/obj/**",
            "_site/**"
          ]
        }
      ],
      "dest": "api"
    }
  ]

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.

Exécutez la commande docfx serve _site puis cliquer sur API Documentation. Le site devrait ressembler à :

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.

docfx_project obtenu au paragraphe précédent a été réduit a la structure ci desous. A télécharger ici. 

|- articles
|- images
|- src
|- src2
|- index.md
|- toc.yml
|- docfx.json

Nous utiliserons wkhtmltopdf5) pour générer des PDF. Télécharger l'exécutable wkhtmltopdf et l'installer.

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 TOC Include pour inclure le contenu d'autres fichiers TOC. 

- name: Articles
  href: ../articles/toc.yml
- name: Api Documentation
  href: ../api/toc.yml
- name: Another Api Documentation
  href: ../api-vb/toc.yml

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: 

...
  "pdf": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api-vb/**.yml"
        ],
        "exclude": [
          "**/toc.yml",
          "**/toc.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md",
          "pdf/*"
        ],
        "exclude": [
          "**/bin/**",
          "**/obj/**",
          "_site_pdf/**",
          "**/toc.yml",
          "**/toc.md"
        ]
      },
      {
        "files": "pdf/toc.yml"
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ],
        "exclude": [
          "**/bin/**",
          "**/obj/**",
          "_site_pdf/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "**/bin/**",
          "**/obj/**",
          "_site_pdf/**"
        ]
      }
    ],
    "dest": "_site_pdf"
  }

Exécutons maintenant la commande docfx.Vous trouverez le fichier pdf walkthrough3_pdf.pdf généré dans le dossier _site_pdf:

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 : 

"template": [
  "pdf.default",
  "pluginPackages/rest.tagpage.2.31.0/content"
],
 

Voir la page consacrée à cette rubrique ici.

1)
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.
2)
API : Application Programming Interface
3)
Microsoft .NET
4)
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.
5)
wkhtmltopdf est un outil en ligne de commande open source (LGPLv3) pour le rendu HTML en PDF