c# - studio - Genere documentación html automáticamente durante una compilación con Sandcastle

sandcastle visual studio (5)

Debo admitir que me parece un poco escasa la versión actual de Sandcastle; para proyectos grandes, es bastante lento y no es fácil de integrar (ya que aún es temprano).

Para un uso regular, en realidad me resulta más fácil simplemente apuntar el reflector a una carpeta con los archivos dll y xml - IIRC, cargará los archivos xml mientras navegas.

Además, casi siempre tengo el reflector abierto de todos modos ...

[edit] marcado, y sí - comentarios xml se muestran en el panel desensamblador

¿Qué pasos debo seguir para que la documentación HTML se construya automáticamente a través del paso de compilación en Visual Studio? Tengo todos los comentarios en su lugar y el archivo comments.xml que se está generando, y Sandcastle instalado. Solo necesito saber qué agregar al paso posterior a la creación para generar los documentos.

Te recomiendo que instales Sandcastle Help File Builder de Codeplex .

Puede ejecutar esto desde la línea de comando, por ejemplo, desde un evento Post-Build. La línea de comando más simple es:

<install-path>/SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle es muy lento, así que solo lo ejecuto para Release Builds. Para ello, cree un evento Post-Build con un comando como el siguiente, que pasa el nombre de la configuración a un archivo por lotes:

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)

Luego, dentro del archivo de proceso por lotes puede probar si el primer argumento es "Liberar" y, de ser así, ejecutar SandcastleBuilderConsole.exe.

Instalar estos:

NDoc: http://prdownloads.sourceforge.net/ndoc/NDoc-v1.3.1.msi?download

Taller de ayuda HTML: http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

A continuación, utilice la línea de comando NDocConsole.exe para generar documentación en forma MSDN o CHM:

@c: / progra ~ 1 / NDoc / NDocConsole.exe MyCode.dll, MyCode.xml -Documenter = MSDN-CHM

Yo mismo he creado una herramienta externa para esto y le he dado un atajo, pero como decía el cartel anterior, puedes conectarlo a un evento posterior a la creación y listo.

(PD. He estado utilizando la configuración anterior desde hace unos años y estoy muy contento con ella)

Una forma fácil de hacer esto como se sugiere arriba es usar Sandcastle Help File Builder. Se han realizado algunos cambios en el proceso de compilación desde la línea de comandos y ahora estos proyectos pueden compilarse con MSbuild en lugar de SandcastleBuilderConsole.exe. Entonces todo lo que tienes que hacer es:

MSbuild.exe ProjectName.shfb

Se han realizado algunos cambios desde que se hizo esta pregunta. Sandcastle ya no incluye SandcastleBuilderConsole.exe . En su lugar, utiliza el viejo y simple MSBuild.exe .

Integrar esto con Visual Studio aquí es lo que hice:

Coloque esto en su evento Post-build:

IF "$(ConfigurationName)"=="Release" Goto Exit "$(SystemRoot)/microsoft.net/framework64/v4.0.30319/msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName/doc/DocumentationProjectName.shfbproj" :Exit

Esto hará que Visual Studio cree su documentación, solo cuando construya en modo "Release". De esta forma, no estará esperando por siempre cuando construya en modo "Debug" durante el desarrollo.

Un par de notas:

Mi sistema es de 64 bits, si el tuyo no lo es, reemplaza framework64 con framework en la ruta a msbuild.exe .
La forma en que lo configuro es para documentar cada proyecto en mi solución individualmente. Si tiene un archivo de proyecto "Sandcastle Help File Builder" que incluye varios proyectos juntos, entonces probablemente desee deshacerse de ProjectName/ y trasladar el doc al directorio de la solución. En este caso, solo querrá poner los comandos de evento Post-build en el proyecto que se construyó ÚLTIMO en su solución. Si lo coloca en el evento Post-build para cada proyecto, entonces reconstruirá su documentación para cada proyecto que se construya. No hace falta decir que estarás sentado allí un tiempo. Personalmente prefiero documentar cada proyecto individualmente, pero así soy yo.

Instalar Sandcastle y "Sandcastle Help File Builder".

Si no sabe cómo configurar Sandcastle y el "Sandcastle Help File Builder" correctamente, siga estos pasos:

Descarga e instala Sandcastle desde http://sandcastle.codeplex.com/ (si tienes un sistema de 64 bits, necesitarás agregar una variable de entorno. Las instrucciones están aquí .
Descargue e instale "Sandcastle Help File Builder" desde http://shfb.codeplex.com/ (ignore las advertencias sobre MSHelp2 si obtiene alguna. No la necesitará).
Una vez que los tenga instalados, utilice "Sandcastle Help File Builder" para crear un nuevo proyecto de documentación. Cuando te pregunte dónde guardar el archivo, guárdalo en la carpeta de documentación que tienes en tu solución / proyecto. http://www.chevtek.com/Temp/NewProject.jpg
Después de crear un nuevo proyecto, deberá elegir qué tipo de documentación desea crear. Un archivo de ayuda de Windows compilado, un sitio web o ambos. http://www.chevtek.com/Temp/DocumentationType.jpg
Si guardó el archivo del proyecto SHFB en el directorio donde desea que se genere su documentación, puede omitir este paso. Pero si desea que la documentación generada se coloque en otro lugar, entonces necesita ajustar la ruta de salida. http://www.chevtek.com/Temp/OutputPath.jpg NOTA: Una cosa a tener en cuenta acerca de la ruta de salida (lo que me frustró durante una hora) es que cuando se verifica el sitio web como el tipo de documentación que desea, sobrescribirá el contenido en su ruta de salida. Lo que olvidan decirle es que SHFB restringió deliberadamente ciertas carpetas para que no se incluyan como parte de la ruta de salida. El escritorio es una de esas carpetas. Su ruta de salida no puede estar en el escritorio, ni siquiera en una subcarpeta del escritorio. Tampoco puede hacerlo en Mis documentos, pero PUEDE ser una subcarpeta de mis documentos. Si obtiene errores al crear su documentación, intente cambiar la ruta de salida y vea si eso la soluciona. Consulte http://shfb.codeplex.com/discussions/226668?ProjectName=shfb para obtener detalles sobre esto.
Finalmente, deberá agregar una referencia al proyecto que desea documentar. Si está haciendo proyectos individuales como yo, entonces, para cada archivo de proyecto SHFB que cree, hará referencia al archivo .CSPROJ correspondiente. Si tiene un proyecto SHFB para su solución completa, entonces encontrará el archivo .SLN para su solución. (sandcastle también funciona si hace referencia a las DLL compiladas, pero como lo está integrando con Visual Studio, creo que tiene más sentido hacer referencia a los archivos de proyecto / solución. Esto también puede significar que realmente no importa qué proyecto realice el evento posterior a la creación ya que hace referencia al código en lugar de a los archivos DLL, pero es mejor estar seguro y ponerlo en el último proyecto que se haya creado) http://www.chevtek.com/Temp/AddSource.jpg
Guarde el proyecto y puede cerrar "Sandcastle Help File Builder". Ahora todo está configurado. Solo asegúrese de colocar el archivo de proyecto de documentación en la carpeta adecuada a la que apuntan los comandos de lote en el evento Post-build.

¡Espero que mi breve tutorial te ayude! Fue muy difícil para mí encontrar algún tutorial decente que me mostrara cómo usar el castillo de arena, y mucho menos cómo integrarlo con Visual Studio. Afortunadamente, las búsquedas futuras en google mostrarán esta pregunta.