Uso de SandCastle
Para hacer uso de SandCastle podemos hacerlo de varias maneras, de las cuales mencionaremos dos:
- A través de la creación de la creación de un SandCastle Help File Builder Project en Visual Studio
- Mediante la aplicación SandCastle Help File Builder GUI
NOTA: Por el momento solo se explicará la creación del proyecto de SandCastle a través de Visual Studio.
Tipos de formatos de archivos
A continuación se listan los tipos de formatos de los archivos generados a través de SandCastle:
- HTML Help 1 (chm)
- MS Help Viewer (mshc)
- Open XML (docx)
- Markdown (md)
- Website (HTML/ASP .NET)
SandCastle Help File Builder Project en Visual Studio
La creación un proyecto SandCastle Help File Builder debe hacerce sobre una solución existente con el objetivo de guardar relación con los proyectos que hagan parte de dicha solución.
ATENCIÓN: Para un ejemplo práctico (haz clic aquí para descargar el ejemplo) se muestra la creación de un proyecto SandCastle Help File.
Builder sobre la solución DummyLibrary:
Se crea el proyecto de tipo SandCastle Help File Builder haciendo clic derecho sobre la solución y escoger en el menú [Agregar ... > Nuevo Proyecto ...], buscamos el tipo de proyecto, que para el caso es SandCastle Help File Builder, le damos un nombre al proyecto, por ejemplo DummyDocumentation, y hacemos clic en OK.
Una vez creado el proyecto hacemos clic derecho sobre el mismo y escogemos el ménu Propiedades.
En la pestaña Build de las propiedades del proyecto podemos definir el formato sobre el cual(es) queremos que se generé la documentación y la versión del framework .NET.
En la pestaña Help File de las propiedades del proyecto podemos definir las propiedades de los documentos de salida resultado de la generación de la documentación. Se puede definir el título, el nombre del archivo de salida, la versión de la documentación, el idioma, entre otros. NOTA: Debemos tener especial cuidado en la propiedad Presentation style pues se encuentra ligada al formato escogido, por ejemplo si escogemos Markdown como formato se debe escoger el estilo Markdown content.
Una vez configurado el proyecto de documentación debemos asociar los proyectos a los cuales vamos a generar la documentación, que para el caso será DummyLibrary. Para esto hacemos clic en la carpeta Documentation Sources y escogemos el menú Add Documento Source. Nos abrirá una ventana emergente para buscar el recurso, que para el ejemplo será el .csproj del proyecto DummyLibrary. Hacemos clic en Abrir y debe aparecer la referencia dentro de la carpeta Documentation Sources.
Para generar la documentación solo hacemos Rebuild del proyecto de documentación y generará el(los) documento(s) correspondiente(s) dependiendo del formato escogido. Para ver el resultado solo hay que abrir la carpeta Help (generada en el proceso) incluida dentro de las cartepas del proyecto de la documentación (DummyDocumentation).
El resultado de la generación será el documento HTML Help 1 (DummyDocumentation.chm).
A tener en cuenta...
Por defecto los proyectos de SandCastle vienen con configurados para la visibilidad de ciertos elementos API a la hora de generar la documentación.
Dependiendo de lo que se quiera mostrar o no en la documentación estos deben ser actividados o desactivados. Esto se puede hacer en las propiedades del proyecto SandCastle en la sección Visibility:
Aquí podemos generar documentación o no para miembros hereados (publicos, internos o privados) del framework de .NET, miembros propios (publicos, protegidos, internos, clases selladas, o privados) del código escrito e incluso se pueden definir filtros para seleccionar solo parte de la documentación de una clase en particular (botón Edit API Filter).
En la ventana de API Filter, se puede personalizar lo que se quiera generar en la documentación llegando hasta el punto confirmar que documentación método/propiedad/clase/interface genere documentación o no.