Ce guide expliquera les différentes étapes afin de générer une documentation PDF à partir des commentaires en format XML dans du code C#.
Plusieurs outils permettent de générer une documentation statique en HTML à partir des commentaires en format XML dans notre code. Dans ce guide,l'outil DocFX sera utilisé, celui-ci permet de générer une documentation sous plusieurs formats.
DocFX permet de générer la documentation statique en format HTML à partir de commentaires en XML dans le code.
Il y a plusieurs façons d'installer DocFX. Celle que nous utiliserons est intégrée dans Visual Studio (NuGet) et facilitera notre travail (NuGet).
- Créer un nouveau projet "C# Class Library".
- Clique droit sur le projet dans l’Explorateur de solution -> "Manage NuGet Packages...".
- Installer le package "DocFX.console", il s'ajoutera automatiquement au build target.
- On peut maintenant Build notre projet. La documentation au format HTML sera générée dans le répertoire "_site"
On peut aussi installer DocFX comme outil en ligne de commande, ça impliquera cependant un peu plus de configuration. Il est également possible d'inclure la génération sur un serveur de compilation, cette pratique est largement répandue dans le domaine.
wkhtmltopdf permet de convertir le format HTML en PDF.
À partir d'une console PowerShell avec droits administrateur:
choco install wkhtmltopdf -y
Il faut savoir bien documenter son code! La qualité des commentaires augmentera l'utilité du site généré. Voici quelques directives à suivre pour bien documenter son code en .Net.
Cette procédure expliquera comment générer un fichier PDF avec notre documentation.
- Configurer la génération PDF dans le fichiers docfx.json en ajoutant sous la configuration "build", la configuration ici-bas :
"pdf": {
"content": [
{
"files": [
"api/**.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/**"
]
}
],
"wkhtmltopdf": {
"additionalArguments": "--enable-local-file-access"
},
"dest": "_site_pdf"
}- À la racine du projet, créer un répertoire "pdf"
- Dans ce dernier, créer un fichier "toc.yml" et copier les lignes suivantes :
Prendre note que "name" et "href" doivent être alignés
- name: Articles
href: ../articles/toc.yml
- name: Api Documentation
href: ../api/toc.yml- Compiler le projet pour générer la documentation sous forme de PDF. Il apparaitra dans le répertoire "_site_pdf"
- Chemin d’accès au projet trop long. Modifier l'emplacement du projet pour avoir un chemin d'accès plus court.
- Redémarrer visual studio après l’installation de wkhtmltopdf
- Could not load SDK resolver. Conflit entre vs 2017 et 2019. Désinstaller vs 2017 et réparer 2019. dotnet/docfx#6162
Voici un exemple de fichier "docfx.json"
{
"metadata": [
{
"src": [
{
"files": [
"**.csproj"
],
"src": ""
}
],
"dest": "api",
"disableGitFeatures": false,
"disableDefaultFilter": false
}
],
"build": {
"content": [
{
"files": [
"api/**.yml",
"api/index.md"
]
},
{
"files": [
"articles/**.md",
"articles/**/toc.yml",
"toc.yml",
"*.md"
]
}
],
"resource": [
{
"files": [
"images/**"
]
}
],
"overwrite": [
{
"files": [
"apidoc/**.md"
],
"exclude": [
"obj/**",
"_site/**"
]
}
],
"dest": "_site",
"globalMetadataFiles": [],
"fileMetadataFiles": [],
"template": [
"default"
],
"postProcessors": [],
"markdownEngineName": "markdig",
"noLangKeyword": false,
"keepFileLink": false,
"cleanupCacheHistory": false,
"disableGitFeatures": false
},
"pdf": {
"content": [
{
"files": [
"api/**.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/**"
]
}
],
"wkhtmltopdf": {
"additionalArguments": "--enable-local-file-access"
},
"dest": "_site_pdf"
}
}Pour plus d'informations, lire la documentation officielle.
https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
https://dotnet.github.io/docfx/tutorial/walkthrough/walkthrough_generate_pdf.html
https://developers.de/2018/01/11/publish-xml-documentation-asp-net-core/