Documentation classe Suggestions

Question

Nous sommes une boutique Microsoft, concentrée sur l'utilisation de C #. Nous avons plusieurs projets, y compris les sites Web, les services Windows, et les bibliothèques de classes, que les commentaires XML incorporer.

Je cherche à générer des documents HTML style MSDN pour chaque projet et le déployer sur un emplacement centralisé que tous les développeurs peuvent facilement accéder. Je veux aussi automatiser ces étapes afin qu'ils puissent être exécutés à intervalles réguliers, donc je, et les autres développeurs, ne pas besoin de vous soucier de ne pas oublier de générer et de déployer de nouveaux documents chaque fois qu'une modification est apportée. Je l'ai regardé et Sandcastle Doxygen et les deux semblent être de bonnes options pour générer la documentation que je veux, mais je besoin de conseils sur une bonne façon d'automatiser la génération de celui-ci, comme dans un travail de nuit ou quelque chose.

Tout le monde là-bas faire quelque chose comme ça? Je ne suis pas vendu sur le résultat final étant HTML; surtout s'il y a une meilleure idée.

EDIT:

Je vous remercie toutes les bonnes idées. Il y a deux routes maintenant que je peux étudier, mais je ne sais pas qui fonctionnera le mieux jusqu'à ce que je me salir les mains. Le Sandcastle Help File Builder me semble offrir les meilleures options pour ce que je cherche à faire, donc je vais donner le feu vert à cette suggestion. Cependant, si j'avais plus de temps pour travailler sur la solution XSLT et CSS pour obtenir les données XML à la recherche juste, je poursuivre cette suggestion d'abord.

Merci encore à tous!

Answer 1

Jetez un oeil à Sandcastle Help File Builder . Cette utilisation autonome des projets, de sorte que vous pouvez les construire aussi souvent que vous le souhaitez (par exemple la nuit, ou dans le cadre de votre système continu d'intégration chaque fois qu'un changement est cochée dans).

Answer 2

Vous n'avez pas besoin d'outils tiers pour générer la documentation bien: compilateur C # peut émettre la documentation des commentaires XML-en XML et tout ce que vous avez besoin est de concevoir un beau CSS pour l'afficher dans le navigateur. Si vous n'êtes pas satisfait, vous pouvez également créer votre propre XSLT-transoformation avant d'appliquer CSS, comme décrit (voir un exemple de CSS dans les commentaires!).

Vous pouvez également prendre cette documentation XML et l'améliorer en utilisant quelque chose comme NDoc . Voici un sur la façon de le faire, malheureusement quelque peu dépassée.

Vous pouvez construire manuellement que la documentation de votre projet dans un seul fichier XML en exécutant le compilateur avec le paramètre /doc:documentationfilename.xml.

Vous pouvez également indiquer dans Visual Studio (Propriétés du projet -> Documentation) pour ajouter cette option à chaque construction de votre projet, de sorte que le fichier XML sera généré à chaque fois que vous construisez votre projet. Vous pouvez ensuite accrocher les événements post-construction pour copier le fichier XML à votre référentiel.

Vous pouvez également configurer votre MS Miser sur votre Team Foundation Server pour construire votre documentation et le copier dans le référentiel d'une manière similaire (/p:DocumentationFile=fileName.xml);

Answer 3

Je le fais avec nos projets. En fait, nous utilisons doxywizard pour mettre en place la configuration Doxyfile, qui définira les spécifications pour le code HTML généré. Puis, dans une étape de serveur de build je Invoke "doxygen Doxyfile".

Notre Doxyfile est configuré pour générer les fichiers doxygen dans une zone visible de notre serveur web. Ainsi, chaque tronc commettras à des causes les documents à reconstruire automatiquement.