Sugerencias de documentación de clase

Question

Somos un taller de Microsoft, concentrados en usar C#. Tenemos varios proyectos, incluidos sitios web, servicios de Windows y bibliotecas de clase, que incorporan comentarios XML.

Estoy buscando generar documentación HTML de estilo MSDN para cada proyecto y implementarla en una ubicación centralizada a la que todos los desarrolladores puedan acceder fácilmente. También quiero automatizar estos pasos para que se puedan ejecutar a intervalos regulares para que yo, y los otros desarrolladores, no deban preocuparme por recordar generar e implementar una nueva documentación cada vez que se realiza un cambio. He mirado a Sandcastle y Doxygen y ambas parecen ser buenas opciones para generar la documentación que quiero, pero necesito consejos sobre una buena manera de automatizar la generación, como en un trabajo nocturno o algo así.

¿Alguien por ahí haciendo algo como esto? No me venden en el resultado final HTML; Especialmente si hay una mejor idea.

EDITAR:

Aprecio todas las buenas ideas. Hay un par de rutas ahora que puedo investigar, pero no sabré cuál funcionará mejor hasta que me ensucie las manos. El Sandcastle Help File Builder parece ofrecerme las mejores opciones para lo que estoy buscando hacer, así que daré el visto bueno a esa sugerencia. Sin embargo, si tuviera más tiempo para trabajar en la solución XSLT y CSS para que los datos XML se vieran bien, seguiría esa sugerencia primero.

¡Gracias de nuevo a todos!

Answer 1

Echa un vistazo a Sandcastle Help File Builder. Esto utiliza proyectos independientes, por lo que puede construirlos tan a menudo como desee (por ejemplo nocturno o como parte de su integración continua sistema cada vez que se registra un cambio).

Answer 2

No necesita ninguna herramienta de terceros para generar una buena documentación: el compilador de C# puede generar la documentación de los comentos de XML en XML y todo lo que necesita es diseñar un buen CSS para mostrarla en el navegador. Si no está satisfecho, también puede generar su propia transformación XSLT antes de aplicar CSS, Como se describe aquí (¡Busque un ejemplo de CSS en comentarios!).

Alternativamente, puede tomar esta documentación XML y mejorarla usando algo como NDOC. Aquí hay un Buen articulo sobre cómo hacerlo, desafortunadamente algo desactualizado.

Puede construir manualmente solo la documentación de su proyecto en un solo archivo XML ejecutando el compilador con /doc:documentationfilename.xml parámetro.

También puede indicar en Visual Studio (Propiedades del proyecto -> Documentación) para agregar esta opción a cada compilación de su proyecto, de modo que se genere el archivo XML cada vez que cree su proyecto. Luego puede enganchar eventos posteriores a la construcción para copiar el archivo XML a su repositorio.

También puede configurar su MS Build en su servidor de Foundation Team para construir su documentación y copiarla en el repositorio de manera similar (/p:DocumentationFile=fileName.xml);

Answer 3

Hago eso con nuestros proyectos. Básicamente, usamos DoxyWizard para configurar la configuración DoxyFile, que establecerá las especificaciones para el HTML generado. Luego, en un paso del servidor de compilación, invoco "doxygen doxyfile".

Nuestro DoxyFile está configurado para generar los archivos Doxygen en un área visible desde nuestro servidor web. Por lo tanto, cada compromiso con el tronco hace que la documentación se reconstruya automáticamente.