lunes, 10 de diciembre de 2007

Documentación Técnica de la Solución

Hola!
Me gustaría poder generar una documentación técnica del código fuente de mi aplicación y que quede escrita de tal forma que parezca a la ayuda del msdn o la del TechNet. Esto es posible mediante el uso del SandCastle y una herramienta que provee una interfaz gráfica que lo hace utilizable me refiero al SHFB Sandcastla Help File Builder.

Generar documentación técnica de mi código

Sandcastle es una herramienta que Microsoft distribuye de manera gratuita y su utilización es fundamental para generar documentación conceptual y técnica de las librerías de nuestras soluciones escritas en .Net Framework; Para crear la documentación técnica, Sandcastle toma básicamente un archivo .dll y un archivo de comentarios .xml, se apoya en la reflection y genera un archivo con un formato similar a la documentación técnica del MSDN y TechNet. La utilización de Sandcastle es muy compleja porque carece de Interfaz Gráfica de Usuario por tal razón su utilización nos remite a la línea de comandos, dichos comandos son molestos de escribir y ejecutar; y aunque se pueden crear archivos .bat que automaticen la tarea vale la pena mencionar que la creación de éstos demanda mucho tiempo y en consecuencia dinero.

Para dar respuesta a la complejidad de uso del Sandcastle, en los últimos meses aparece publicado el Sandcastle Help File Builder SHFB quien presenta una GUI que encapsula la complejidad de la secuencia de comandos que originalmente trae el Sandcastle. El proceso Team Build del Team Foundation Sever de Team System tiene la característica de poder incorporar scripts que se ejecutan durante el Build, dichos scripts podrían referenciar el SHFB para que genere automáticamente la documentación técnica de la solución y si se desea, que posteriormente haga un despliegue de la documentación en formato HTML directamente sobre el Team Portal de Team System. La escritura de estos scripts de Team Build tampoco es fácil pero se espera que en diciembre el equipo de Microsoft distribuya un CTP que facilite dicho proceso.

El SHFB genera la documentacion en formato CHM, un sitio web con un indice entre otros formatos, si hay varias dll se crea un nodo principal en el índice que referencia dicha dll

Cómo instalarlo?

  1. Descarga e instala el HtmlHelp:
    [http://go.microsoft.com/fwlink/?linkid=14188]
  2. Descarga e instala el Sandcastle de Microsoft: [http://www.microsoft.com/downloads/details.aspx?FamilyID=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en],
  3. Descarga e instalael Sandcastle Help File Builder:
    [http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=8261]

Una prueba de funcionamiento

1) Asegurate de tener el archivo xml de comentarios
en la carpeta bin de tu proyecto, busca la dll que quieres documentar, el nombre de la dll debe existir tambien con la extension xml por ejemplo Negocios.dll debe tener el archivo de comentarios Negocios.xml, de no ser así se puede crear fácilmente desde visual studio de la siguiente manera,
1. Clic derecho sobre el proyecto/propiedades
2. En la pestaña generar bajo la region Resultado das clic sobre el la caja de verificación:
Archivo de documentación XML
3. Guardar cambios y luego clic derecho sobre el proyecto/volver a generar

Abre el SHFB
1. Clic en Proyecto/Nuevo proyecto
2. Clic en el botón Add, navega hasta las ubicacion de los dos archivos el .dll y el .xml
3. Clic en documentación/Build Project

Listo!