Class Documentation Suggestions

Question

Somos una tienda de Microsoft, concentrada en el uso de C#. Tenemos varios proyectos, incluidos sitios web, servicios de Windows y bibliotecas de clase, que incorporan comentarios XML.

Estoy buscando generar documentación HTML estilo MSDN para cada proyecto y desplegarlo en una ubicación centralizada a la que todos los desarrolladores puedan acceder fácilmente. También quiero automatizar estos pasos para que puedan ejecutarse a intervalos regulares, por lo que ni yo ni los demás desarrolladores debemos preocuparnos de recordar generar e implementar nueva documentación cada vez que se realice un cambio. Miré a Sandcastle y Doxygen y ambos parecen ser buenas opciones para generar la documentación que quiero, pero necesito asesoramiento sobre una buena forma de automatizar la generación, como en un trabajo nocturno o algo así.

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

EDIT:

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 Creador de archivos de ayuda de Sandcastle parece ofrecerme las mejores opciones para lo que estoy buscando hacer, así que le doy la bienvenida 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 vean correctamente, buscaría esa sugerencia primero.

Gracias de nuevo a todos!

Answer 1

Eche un vistazo a Sandcastle Help File Builder. Esto utiliza proyectos independientes, por lo que puede compilarlos tantas veces como desee (por ejemplo, todas las noches o como parte de su sistema continuous integration cada vez que ingrese un cambio).

Answer 2

Lo hago 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.

Answer 3

No necesita herramientas de terceros para generar una buena documentación: el compilador C# puede generar la documentación de comentarios XML en XML y todo lo que necesita es diseñar un CSS agradable para mostrarlo en el navegador. Si no está satisfecho, también puede generar su propia XSLT-transoformación antes de aplicar CSS, as described here (busque un ejemplo de CSS en los comentarios).

Como alternativa, puede tomar esta documentación XML y mejorarla usando algo como NDoc. Aquí hay un nice article acerca de cómo hacerlo, lamentablemente algo desactualizado.

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

También puede indicar en Visual Studio (Propiedades del proyecto -> Documentación) para agregar esta opción a cada compilación de su proyecto, para que el archivo XML se genere cada vez que construya su proyecto. A continuación, puede enlazar eventos de creación posterior para copiar el archivo XML a su repositorio.

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