Ludovic ROLAND

Blog technique sur mes expériences de développeur.

Générez la documentation HTML de vos projets C# avec SHFB

24 janvier 2016

Ce qu’il y de bien avec le Java c’est la javadoc et plus particulièrement la possibilité de la générer au format HTML que ce soit à l’aide d’un IDE ou d’outils de build comme Maven ou Gradle.

Ne nous mentons pas, si les possibilités de faire de la documentation en C# sont grandes (bien que le format XML soit un peu verbeux…), le fait de ne pas pouvoir la générer au format HTML facilement par la suite est un gros manque.

Dans ce billet, je vous propose donc de voir pas à pas comment générer la documentation au format HTML de vos projets C# à l’aide d’un petit utilitaire nommée SHFB.

Le projet SHFB

Le projet SHFB (Sandcastle Help File Builder) est un outil graphique permettant de générer la documentation d’un projet Visual Studio si celle-ci est bien au format XML et respecte les guides de programmation C#.

Il s’agit d’un projet Open-source, longtemps porté par Microsoft. Il est maintenant laissé à la communauté.

Si vous êtes curieux du code source, n’hésitez pas à jeter un coup d’oeil au dépôt GitHub du projet !

Télécharger et installer le projet

Le projet est disponible au téléchargement directement sous la forme d’une archive au format zip depuis la page des releases GitHub.

Une fois l’archive téléchargée, décompressez la et lancez l’installation en exécutant le fichier “SandcastleInstaller.exe”.

L’installateur se lance.

Sur la page “Sandcastle Help File Builder and Tools”, cliquer sur “Install SHFB”.

L’installateur spécifique au projet SHFB se lance alors. Il s’agit d’une installation Windows Classique.

Vous pouvez ensuite accéder à la page suivante “Sandcastle Help File Builder Visual Studio Package” et installer les composants relatifs aux versions de Visual Studio que vous utilisez. Dans mons cas, il s’agit de Visual Studio 2013 et Visual Studio 2015.

Cliquer sur “Install Package” pour lancer l’installation.

Vous pouvez ensuite accéder à la page suivante “MAML Schema IntelliSense” et, une nouvelle fois, installer les composants relatifs aux versions de Visual Studio que vous utilisez.

Finalement, vous pouvez passer à la dernière étape de l’installation en vous rendant sur la page suivante “MAML Snippet Files” et, pour ne rien changer aux étapes précédentes, installer les composants relatifs aux versions de Visual Studio que vous utilisez.

Une fois l’installation terminée, vous pouvez lancer l’outil en le sélectionannt dans l’explorateur de programme Windows.

Générer la documentation

Pré-requis

Avant de se lancer dans la génération de la documentation, il convient de configurer les options de compilation du projet comme le permettant.

Pour cela, ouvrez le projet pour lequel vous souhaitez générer la documentation dans Visual Studio puis rendez-vous ces Propriétés et plus particulièrement l’onglet Build. Cochez alors “Fichier de documentation XML” comme dans la capture d’écran ci-dessous :

Une fois la case cochée, il convient de regénérer le projet.

Retour à la documentation

Pour générer la documentation, il convient donc de lancer l’outil Sandcastle Help File Builder si vous ne l’aviez pas déjà fait. La fenêtre suivante devrait alors s’afficher :

Il convient ensuite de créer un nouveau projet Sandcastle.

Pour cela, cliquez sur “File” puis “New Project…“.

Une fois le projet créé, il convient d’ajouter des “Documentation Sources”.

Choisissez alors le fichier XML généré via le compilateur :

Les fichiers devraient alors s’ajouter dans notre petit outil comme en témoigne la capture d’écran ci-dessous :

Dans la fenêtre principale, il convient alors de sélectionner le format de sortie. Dans notre cas, nous souhaitons générer la documentation au format HTML, il convient donc de cocher choisir “Website (HTML/ASP.NET)”.

Pour lancer la génération, il suffit alors de cliquer sur l’icône :

La documentation est alors générée au format HTML dans le dossier “Help” et devrait ressembler à ça :

Gérer les erreurs de génération

Il peut être nécessaire d’ignorer des assemblies au moment de la génération pour éviter les erreurs au moment de la génération de la documentation.

Pour se faire, rendez-vous dans la fenêtre “Project Properties” et plus particulièrement dans la section “Plug-Ins”. Sélectionnez alors l’entrée “Assembly Binding Redirection” en la cochant et cliquez sur le bouton “Configure” :

Dans la fenêtre qui s’ouvre, sélectionnez l’onglet “Ignore If Unresolved” et dans le champ “Assembly Name to Ignore” renseigner l’assembly (par exemple “System.Net.Primitives”) et cliquer sur le bouton “Add” :

Si vous relancez la génération, celle-ci devrait alors aboutir.

Commentaires