Génération de documentation avec Sandcastle Help File Builder

L'ajout d'un assemblage est assez simple, nous allons simplement cliquer sur Add, et sélectionner, dans le répertoire de compilation, à la fois le fichier dll et le fichier XML. Si nous ne sélectionnons qu'un seul des deux (ou s’ils ont été générés dans des répertoires différents), il suffit de sélectionner l'assemblage, et cliquer sur Edit pour faire apparaître la fenêtre suivante :

Nous ne nous intéresserons pas à l'option CommentsOnly dans ce tutoriel. Elle permet en fait principalement de partager entre plusieurs projets le sommaire et la liste des namespaces à documenter, dans le cas, par exemple, de deux jeux de documentation à générer, un en intranet documentant l'intégralité du code, l'autre externe ne documentant que les propriétés et méthodes publiques.

SandCastle nous permet de ne documenter qu'un sous-ensemble des espaces de noms de notre projet.
Pour sélectionner les espaces de noms en question, il suffit de cliquer sur le bouton Namespaces, et de cocher/décocher les espaces de noms désirés.

De plus, ce dialogue nous permet de renseigner les sommaires des namespaces, la documentation des namespaces n'étant pas gérée par le framework.
Le bouton Prj Summary, lui, nous permet de renseigner un sommaire pour le projet.

Pour tester ces sections, nous allons ajouter un commentaire court… et faire un test de génération.
Après quelques secondes de génération, le processus s'arrête avec une erreur…

En effet, comme mentionné précédemment, nous avons, dans le namespace Core, une dépendance sur log4net… que nous n'avons pas rajoutée.
Ce que nous allons faire tout de suite…

Pour sélectionner les dépendances, il suffit de les ajouter dans les propriétés de projet, dans la rubrique build, à la ligne dependencies.

Dans cette fenêtre, nous pouvons, au choix, ajouter des dépendances sur des fichiers, des répertoires, ou des dll dans le GAC.

Nous pouvons dans ce dialogue, choisir soit de stocker le chemin de façon absolue, soit de façon relative.

Une fois cette action d'ajout de dépendances effectuée, nous pouvons désormais faire notre première génération de documentation. Pour l'exemple, je ne vais générer que le namespace Core et le namespace global.

Nous avons bien sûr la possibilité de modifier les en-têtes et pieds de page des pages générées. Pour cela, nous avons des champs tout prêts, dans la section « Help File ».

Ces champs nous permettent de modifier, dans l'ordre :

• CopyRightHref : le lien du copyright ;
• CopyRightText : le texte du copyright ;
• FeedBackEmailAddress : l'adresse e-mail de contact ;
• FooterText : le texte d'information du pied de page ;
• HeaderText : le texte d'information de l'en-tête ;
• HelpTitle : le titre du fichier ;
• HTMLHelpName : le nom du fichier ;
• Language : la page de langue à utiliser ;
• Preliminary : si vrai, affiche un texte indiquant que la doc n'est pas définitive ;
• PresentationStyle : le style du fichier.

Nos en-têtes et pieds de page sont bien visibles, mais manquent un peu de « punch ».
Qu'à cela ne tienne, nous allons modifier les fichiers de templates.

Pour cela, nous allons nous rendre dans le répertoire d'installation de SandCastle Help File Builder, dans le sous-répertoire SharedContent. Nous y trouverons tous les contenus partagés, et localisés, sous forme de fichiers XML.

Dans mon cas, j'utilise le Style Hana, en langue française. Je vais donc éditer le fichier HanaBuilderContent_fr-FR.xml.

<?xml version="1.0" encoding="utf-8"?>
<content xml:space="preserve">
    <!-- NOTE: This file must appear LAST in the list of content files
               so that these items override the matching items in the
               stock content files! -->

    <item id="header"><span style="color: DarkGray">{@HeaderText} {@Preliminary}</span></item>

    <item id="footer">{@FooterText}{@Comments} {@Copyright}</item>

</content>

Dans ce fichier, nous voyons bien que le header a comme propriétés d'avoir un texte gris, compose des éléments HeaderText et Preliminary, et que le Footer est la concaténation des éléments FooterText, Comments et Copyright.

Dans un premier temps, je vais changer mon header et mon footer de façon à ce qu'ils soient affichés en blanc sur fond bleu (je sais, je ne suis pas un designer ;))

<?xml version="1.0" encoding="utf-8"?>
<content xml:space="preserve">
    <!-- NOTE: This file must appear LAST in the list of content files
               so that these items override the matching items in the
               stock content files! -->

    <item id="header"><span style="width:100%;background-color:LightBlue;color: White">
            {@HeaderText} {@Preliminary}</span></item>

    <item id="footer"><span style="width:100%;background-color:LightBlue;color: White">
            {@FooterText}{@Comments} {@Copyright}</span></item>

</content>

C'est beau, non ???


… Non, parce que mon cher chef de projet veut absolument voir le texte préliminaire en jaune…
Et que je ne trouve pas cette donnée dans mon fichier XML…

C'est normal, elle se trouve en fait dans SharedBuilderContent_fr-FR.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- Translations provided by Thierry Huguet and his colleagues -->
<content xml:space="preserve">
    <!-- NOTE: This file must appear LAST in the list of content files
               so that these items override the matching items in the
               stock content files! -->

    <!-- reference_content.xml overrides -->
    <item id="rootTopicTitle">{@RootNamespaceTitle}</item>
    <item id="rootTopicTitleLocalized">Espaces de noms</item>
    <item id="rootLink"><referenceLink target="R:Project">{@RootNamespaceTitle}</referenceLink></item>
    <item id="productTitle">{@HtmlEncHelpTitle}</item>
    <item id="runningHeaderText">{@HtmlEncHelpTitle}</item>

    <item id="locationInformation">Assembly: {0} (Module: {1}) Version: {2}</item>
    <item id="assemblyNameAndModule">{0} (in {1})<br/><b>Version:</b> {2}</item>

    <!-- shared_content.xml overrides -->
    <item id="copyCode">Copy</item>

    <item id="locale">{@Locale}</item>

    <item id="preliminary"><p style="color: #dc143c; font-size: 8.5pt; font-weight: bold;">[Ceci est une documentation préliminaire, sous réserve de modification.]</p></item>

    <item id="comments"><p />Envoyez vos commentaires sur cette documentation à
        <a id="HT_MailLink" href="mailto:{@UrlEncFeedbackEMailAddress}?Subject={@UrlEncHelpTitle}">{@HtmlEncFeedbackEMailAddress}</a>
        <script type="text/javascript">
        var HT_mailLink = document.getElementById("HT_MailLink");
        var HT_mailLinkText = HT_mailLink.innerHTML;
        HT_mailLink.href += ": " + document.title;
        HT_mailLink.innerHTML = HT_mailLinkText;
        </script></item>

    <!-- To format the copyright HREF and/or copyright text into a message of
         your choosing, you can specify @HtmlEncCopyrightHref and/or
         @HtmlEncCopyrightText in braces -->
    <item id="copyright">{@HtmlEncCopyrightInfo}</item>

</content>

Ça y est, je n'ai plus qu'à mettre à jour l'item preliminary

 <item id="preliminary"><p style="color: Yellow; font-size: 8.5pt; font-weight: bold;">
 [Ceci est une documentation préliminaire, sous réserve de modification.]</p></item>

OK, mon chef de projet est content. Mais il manque encore une chose, à savoir un joli logo dans l'en-tête, pour faire plus pro.
Cette manip n'est heureusement pas beaucoup plus difficile. Il suffit de modifier, une fois de plus, le fichier HanaBuilderContent_fr-FR.xml.
Sauf que là, se pose la question, comment ajouter une image ?
Pour cela, dans l'éditeur, nous irons dans la rubrique « Additional Content », sur la ligne « Additional Content », cliquer sur le bouton « … »

Une fois dans l'éditeur de contenus, je vais aller chercher le logo que je veux ajouter, ici, dvp.png. Ce logo va pouvoir être accédé depuis le fichier chm comme s'il était à la racine d'un site.

Je vais ensuite modifier mon fichier pour obtenir ceci

    <item id="header"><span style="width:100%;background-color:LightBlue;color: White">
          <img src="dvp.png"/>  {@HeaderText} {@Preliminary}</span></item>

Et, après génération, mon fichier d'aide aura dorénavant le look suivant :

Notre fichier d'aide commence à ressembler à quelque chose de sympathique.
Par contre, il reste un peu maigre en informations, et plutôt inutile à fournir dans l'état à un client (interne ou externe), dans le cas d'une API.

Nous allons donc ajouter des exemples de code dans notre fichier.
Le tag code existe déjà, avec un tag example, dans les tags de base de la documentation Visual studio. Le problème est que ces tags ne font pas de différence entre C# et vb.net.

Heureusement, SandCastle Help File Builder fournit un composant de compilation supplémentaire, nommé « code blocks », et dont le but est justement de résoudre ce problème. Pour cela, nous modifierons notre code de cette façon :

 /// <summary>
        /// Logs a debug message
        /// </summary>    
        /// <example>The debug messages can be logged using the following code
        /// <code lang="vbnet">LogFactory.LogDebug(10)</code>
        /// <code lang="c#">LogFactory.LogDebug(10);</code>
        /// </example>
        /// <param name="message">The message.</param>
        public static void LogDebug(string message) {
            log.Debug(message);
        }

Il sera ensuite traduit, dans le fichier XML généré, par :

            <example>The debug messages can be logged using the following code
            <code lang="vbnet">LogFactory.LogDebug(10)</code>
            <code lang="c#">LogFactory.LogDebug(10);</code>
            </example>

Ensuite, nous allons modifier, dans SandCastle Help File Builder, la liste des composants de compilation utilisés. Pour cela, dans la rubrique build, nous allons cliquer sur le bouton « … » de la ligne Componentconfigurations.

Puis, dans la rubrique Available build components, nous allons sélectionner « Code Block Component », et cliquer sur le bouton d'ajout, en bas, à gauche, de façon à obtenir l'écran suivant :

Et avec ces simples actions, nous aurons dorénavant les exemples dans notre langage de choix dans le fichier d'aide, comme ci-dessous :

Pour cette partie, nous allons admettre que mon projet est un projet modèle, avec toute la documentation qui va bien.
Maintenant que nous pouvons identifier facilement ma société, mon nom de projet, et que j'ai ajouté un moyen pour contacter l'équipe de projet depuis la doc, je vais vouloir étendre encore ma documentation. Nous pourrions imaginer deux cas « métier » où cela serait utile.
Le premier est celui de la fourniture de dll tierce partie, en externe ou en interne.
Si vous avez déjà utilisé des composants fournis par un revendeur, vous vous êtes sûrement aperçu qu'une grande partie de la documentation contient des exemples d'utilisation des bibliothèques fournies.
Le second cas, plus particulièrement répandu en interne, est celui d'une documentation projet un peu plus extensive, qui va contenir en plus de la documentation des assemblages, des classes, et des fonctions, une partie de description des choix d'architecture, et qui va être fournie en « package d'accueil » aux nouveaux venus.

Nous allons utiliser des documents au format HTML, qui vont être inclus dans notre fichier d'aide. Dans un premier temps, nous allons devoir évidemment écrire ces fichiers, puis les stocker dans un répertoire de notre choix. Dans notre exemple, nous allons ajouter une partie « Spécification », une partie « Architecture », une partie « Plan de test », et une page d'accueil. Après préparation des différentes pages, mon répertoire de documentation HTML va ressembler à cela :

Une fois les fichiers préparés, nous allons utiliser Sandcastle Help file Builder pour les inclure à notre documentation. Pour cela, nous allons aller dans la rubrique « Additional Content », sur la ligne « Additional Content », cliquer sur le bouton « … »
(En passant, on constate que le placement du contenu additionnel peut se faire soit au-dessus, soit en dessous des espaces de noms.)

Nous allons, dans un premier temps, ajouter les trois dossiers, en cliquant sur le bouton « dossier », puis ajouter le fichier Accueil en cliquant sur le bouton « fichiers ». Notez qu'il existe un bouton éditer, qui permet une édition de la source du fichier HTML. Nous obtenons donc l'écran suivant :

Après une génération du contenu, nous nous rendons néanmoins compte de l'oubli d'un détail, à savoir que les pages « Spécification », « Architecture », et « Plan de test » n'ont pas de descriptif.

En effet, il faut associer à chaque nœud de l'arbre une feuille HTML pour pouvoir avoir un affichage quelconque dans notre fichier de doc. Nous allons donc éditer le sitemap du fichier chm pour pouvoir associer à chaque rubrique une page d'index. Pour cela, nous allons retourner dans la fenêtre d'édition du contenu, cliquer sur le bouton d'édition du sitemp

Dans l'éditeur de sitemap, nous allons ensuite sélectionner les nœuds auxquels nous voulons ajouter une page d'accueil, ici, Architecture, et nous allons faire pointer la page vers une page existante.

Tant que nous y sommes, nous allons aussi réarranger le menu, en mettant en premier Accueil, puis Spécifications, Architecture et Plan de test, en utilisant les boutons haut et bas. Nous allons aussi sélectionner la page d'accueil comme page par défaut, en la cliquant, puis en cliquant le bouton de sélection de page d'accueil, en haut à droite. Le nouveau sitemap aura la représentation suivante :

Sandcastle Help File builder génère alors automatiquement un fichier sitemap, et, à la prochaine génération nous obtenons le fichier de nos rêves ;).