rÉalisation de documentation technique sous visual studio...

9
1 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the- best-way-to-document-a-vb-net-toolkit-library et de RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO 2010 LES PRINCIPALES ÉTAPES DE GÉNÉR ATION 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 ».

Upload: trinhcong

Post on 12-Feb-2019

224 views

Category:

Documents


1 download

TRANSCRIPT

Page 1: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

1 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-way-to-document-a-vb-net-toolkit-library et de

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

Page 2: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

2 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 :

Page 3: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

3 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 :

Page 4: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

4 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 »,

Page 5: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

5 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 :

Page 6: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

6 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 :

Page 7: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

7 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

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

Page 8: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

8 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

best-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 :

Page 9: RÉALISATION DE DOCUMENTATION TECHNIQUE SOUS VISUAL STUDIO ...mariepascal.delamare.free.fr/IMG/pdf/5_documentationCours.pdf · A partir de ces balises, Visual Studio 2010 va automatiquement

9 Marie-pascale Delamare à partir de http://stackoverflow.com/questions/8208193/what-is-the-

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