réalisation de documentation technique sous visual studio 2010 les

RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO 2010
LES PRINCIPALES ÉTAPES DE GÉNÉRATION AUTOMATIQUE D’UNE DOCUMENTATION
TECHNIQUE SOUS VISUAL STUDIO 2010
Il faut créer des fichiers XML à partir de notre code en utilisant “ ’’’ ” en début de ligne accompagné de balises
XML prédéfinies. Par exemple :
Ce travail doit être fait pour chaque fonction, chaque procédure, chaque méthode de chaque classe. C’est donc
un travail assez lourd. Pour le simplifier il existe des outils permettant de générer quasi automatiquement
l’ensemble des balises XML nécessaires. Nous utiliserons l’outil “GhostDoc”.
A partir de ces balises, Visual Studio 2010 va automatiquement générer une documentation XML, mais il faut
pour cela le lui demander. Il faut donc sélectionner les propriétés d’un projet, choisir l’onglet “Compiler” et
cocher « Générer le fichier de documentation XML ».
1
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
À la génération de la solution, le fichier XML sera généré dans le répertoire bin/debug.
Pour transformer ce fichier XML en fichier d’aide HTML on peut utiliser d’autres outils comme nDoc ou
Sandcastle. Nous utiliserons Sandcastle avec son interface graphique pour obtenir des documentations comme
celle-ci :
2
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
INSTALLATION DES OUTILS NÉCESSAIRES
Procédons maintenant aux installations nécessaires. Récupérez sur le serveur de la section les fichiers
GhostDoc_v3.0.zip et SHFBGuidedInstallation_1934.zip.
INSTALLATION DE GHOSTDOC
Dans l’archive GhostDoc_v3.0.zip, lancez l’exécutable GhostDoc v3.0.11216.exe. Acceptez les termes de la
licence et vérifiez que ce programme va s’intégrer à Visual Studio 2010 :
Après installation, vous disposez d’un nouveau menu dans la partie « Outils » de Visual Studio. Au démarrage
de Visual Studio un assistant de configuration de GhostDoc se lance vous demandant d’assigner un raccourci
clavier à la génération automatique des balises XML. Gardez l’option par défaut. Puis choisissez « Create » pour
créer votre configuration. Voilà désormais Ghostdoc est disponible dans Visual Studio :
3
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
INSTALLATION SANDCASTLE
Cette installation est plus longue et plus délicate, soyez attentif à ce que vous faîtes. Dé-zippez l’archive
SHFBGuidedInstallation_1934.zip puis lancez SandcastleInstaller.exe.
Cliquez sur « Next », « Next », « Next », « Next », « Next ». Arrivé sur l’écran d’installation des outils
“SandCastle”
Cliquez sur « Install SandCastle » et conservez les valeurs proposées. Après avoir cliqué sur « Next »,
4
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
Appliquez le patch. Puis
Extraire les langues.
Ensuite extraire les fournisseurs de XML pour les applications web :
5
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
Et enfin extraire les convertisseurs :
Installez les Schémas pour Intellisense :
Installez les constructeurs de fichiers d’aide :
6
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
Pour finir installez le package SandCastle pour Visual Studion 2010 :
Enfin redémarrez votre ordinateur pour que tout fonctionne.
UTILISATION DES OUTILS INSTALLÉS
UTILISATION DE GHOSTDOC
Lancez maintenant votre « projetEtudiant » et ouvrez votre classe « Etudiant ». Sélectionnez votre méthode
CalculerMoyenne et Faites « Outils », « Ghostdoc », « Document this » ou « CTRL SHIFT D ». Complétez les
balises générées. Faites de même pour toutes les autres méthodes de votre classe (accesseurs et constructeurs
compris).
7
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
Générez votre solution et allez dans le répertoire bin/debug de votre « projetEtudiant » :
UTILISATION DE SANDCASTLE
Lancez maintenant l’interface graphique de SandCastle et créez un nouveau projet que vous enregistrez dans
l’espace de votre solution « ProjetEtudiant ».
Dans la partie documentation source ajoutez votre solution « ProjetEtudiant ». Puis dans le menu
« Documentation » choisir « Build Project ». Attendre.
Dans le menu documentation demandez ensuite à voir votre documentation. Voilà ce que vous obtenez :
8
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de
Votre fichier documentation est disponible dans votre solution « ProjetEtudiant », répertoire « Help » sous le
nom « Documentation.chm ». Vous pouvez la visualiser et la livrer avec votre projet.
Si vous lancez « SHFB Project Launcher » et que vous choisissez de voir votre documentation dans Visual Studio
2010, ce projet sera accessible dans l’explorateur de solution.
Désormais vous devrez penser à documenter votre projet au fur et à mesure de sa réalisation.
9
Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-thebest-way-to-document-a-vb-net-toolkit-library et de