miércoles, 24 de diciembre de 2008

Crear documentación al estilo de Visual Studio 2005 usando Sandcastle

Existen varias aplicaciones que nos permiten generar documentación al estilo de la documentación de Visual Studio, en este pequeño artículo hablaremos específicamente de Sandcastle y de Sandcastle Help File Builder GUI.

Antes que nada vamos a instalar los componentes necesarios para poder crear la documentación, utilizaremos el HTML Help WorkShop, Sandcastle, Sandcastle Help File Builder GUI y este último es opcional Visual Studio 2005 SDK Versión 4.0.

Sandcastle permite crear tres tipos de documentación, de tipo HtmlHelp1x, HtmlHelp2x y Website; para la documentación de tipo HtmlHelp1x se utiliza HTML Help Workshop el cual produce un archivo CHM, para la del tipo HtmlHelp2x y Website es necesario el SDK de Visual Studio 2005. Con el HTML Help Workshop es más que suficiente por el momento ya que para la del tipo HtmlHelp2x hay que realizar más pasos para poder integrar esa ayuda con la de Visual Studio 2005.

Los programas a utilizar son el Visual Studio 2005 y Sandcastle Help File Builder GUI este último se encargará de llamar internamente a Sandcastle y a HTML Help Workshop para crear el archivo de documentación.

Bien una vez teniendo todo lo necesario vamos a trabajar en Visual Studio 2005 y habilitar la creación del archivo XML que contendrá la información de todo lo que vayamos documentando, esto se habilita en las propiedades del proyecto en la pestaña Compile

Generate Xml Documentation

Esta hará que al compilar el proyecto se cree un archivo XML por cada ensamblado en nuestro proyecto.

Vamos a crear una clase Helper y una función de ejemplo que vamos a documentar

Public Class Helper

''' <summary>
''' Aquí va la descripción de lo que hace nuestra función
'''
</summary>
''' <param name="variable1">Variable 1 no debe de ser cero</param>
''' <param name="variable2">Variable 2 no debe de ser nulo</param>
''' <returns>Devuelve si es falso o verdadero</returns>
''' <remarks>Lorem ipsum</remarks>
Public Shared Function FunctionSample(ByVal variable1 As Integer, ByVal variable2 As String) As Boolean
Return True
End Function

End Class

Compilamos nuestro proyecto y nos generará el ensamblado y el archivo XML con la información de la documentación

Archivo Xml

Abrimos el Sandcastle Help File Builder GUI y agregamos el ensamblado recién creado para crear la documentación usando el botón Add.

Sandcastle Help File Builder GUI

Modificamos las propiedades PresentationStyle a vs2005, SdkLinkType a Index y verifique que la propiedad HelpFileFormat este en HtmlHelp1x. Presione el botón Build de la barra de herramientas para generar la documentación, si aún no ha guardado el proyecto le solicitará guardarlo, el archivo final estará dentro de la carpeta Help en la misma ruta donde guardo el archivo de proyecto de Sandcastle. Abajo se muestra la imagen con la documentación de la función del ejemplo.

Documentación

Es todo por el momento y gracias por su atención.

Referencias