Sandcastle es un generador de documentación de Microsoft . Produce automáticamente documentación de código de estilo MSDN a partir de información de reflexión de ensamblados .NET y comentarios de documentación XML que se encuentran en el código fuente de estos ensamblados. También se puede utilizar para producir documentación de usuario a partir de Microsoft Assistance Markup Language (MAML) con el mismo aspecto que la documentación de referencia.
Sandcastle es un conjunto de programas de línea de comandos , archivos de configuración, componentes de compilación y archivos XSLT que trabajan juntos para convertir la documentación basada en XML en temas de ayuda aptos para su visualización en un sistema de ayuda. Sandcastle se utiliza normalmente para generar automáticamente documentación HTML compatible con XML y lista para la Web en uno de los tres estilos de presentación integrados a partir de ensamblajes .NET y archivos de documentación XML generados por compiladores . Los archivos HTML resultantes se utilizan luego como entrada para herramientas como HTML Help Workshop para producir ayuda compilada para su distribución con el programa informático correspondiente .
Actualmente, Sandcastle cuenta con una interfaz gráfica de usuario (GUI) liviana como alternativa al proyecto MSBuild , el script por lotes y los scripts de Windows PowerShell que también se proporcionan. También hay varias herramientas de GUI de la comunidad disponibles para Sandcastle, que brindan funciones adicionales y simplifican su uso. [1]
Los SDK de Visual Studio para 2005 y 2008 incluyen versiones CTP más antiguas de Sandcastle, [2] aunque la última versión está disponible en GitHub .
Sandcastle consta de varios programas, no todos los cuales se utilizan en el proceso típico de creación de ayuda. A continuación se enumeran las herramientas más utilizadas.
Dado que en su estado actual Sandcastle por sí solo es bastante complejo de usar, se han ideado herramientas y scripts que pueden automatizar la tarea. Esta sección contiene una lista de dichas herramientas y scripts.
Sandcastle produce archivos HTML basados en XML en un estilo de presentación elegido. (Esto no significa, sin embargo, que los archivos sean compatibles con XHTML ). El HTML se define mediante archivos de transformación XSL que se incluyen en el estilo de presentación particular que se utiliza. Una compilación normalmente utiliza solo un estilo de presentación a la vez.
Los archivos HTML que produce Sandcastle son documentación conceptual (de usuario), que es el resultado de una transformación de temas de Microsoft Assistance Markup Language (MAML), o documentación de referencia, que se genera automáticamente a partir de datos de reflexión y comentarios de documentación XML. Estos dos tipos diferentes de salida HTML comparten el mismo estilo de presentación y se pueden compilar juntos para producir documentación de referencia/usuario mixta.
Los procesos para construir documentación conceptual y documentación de referencia son similares, siendo una de las principales diferencias que la documentación conceptual no requiere el uso del programa MRefBuilder.
La documentación conceptual consta de temas escritos utilizando un esquema de tipo de documento MAML, como instrucciones, guías, resolución de problemas y muchos otros. Sandcastle proporciona una pila de componentes de compilación conceptual (conceptual.config) que resuelve el contenido y los vínculos compartidos, y utiliza archivos XSL para transformar elementos MAML en HTML.
La documentación de referencia se genera automáticamente para las interfaces de programación de aplicaciones (API) administradas a partir de datos de reflexión y comentarios de documentación XML. Se aplica una transformación XSL de "modelo de documento", proporcionada por el estilo de presentación elegido, para definir los archivos que se generarán. Sandcastle proporciona una pila de componentes de compilación de referencia (sandcastle.config) que crea índices en memoria de los datos, resuelve el contenido y los vínculos compartidos y utiliza XSL para generar la salida HTML final.
Sandcastle no produce por sí mismo una salida de ayuda compilada (aunque los archivos HTML que produce se pueden usar como entrada para compiladores de ayuda HTML como HTML Help Workshop y Microsoft Help 2 ).
Por ejemplo, el proceso típico de creación de Help 1.x comienza ejecutando MrefBuilder.exe para generar un archivo de reflexión XML para uno o más ensamblajes. A continuación, la herramienta XslTransform.exe procesa el archivo de reflexión varias veces para aplicar varias transformaciones XSL que agregan datos como un "modelo de documento" e información de versión opcional. A continuación, se genera un manifiesto de tema basado en XML y lo utiliza el programa BuildAssembler.exe, que genera archivos de tema HTML a partir de los datos de reflexión y los comentarios de la documentación XML. CHMBuilder.exe genera y utiliza un archivo de tabla de contenido (TOC) basado en XML, junto con los archivos HTML producidos por BuildAssembler, para generar archivos de proyecto, índice y TOC de HTML Help Workshop. Por último, HTML Help Workshop se utiliza para generar un archivo de ayuda compilado (.chm).
Algunas herramientas se utilizan varias veces durante una única compilación, como XslTransform y BuildAssembler. Según los requisitos, se pueden utilizar otras herramientas y transformaciones XSL en varias etapas durante el proceso para modificar el resultado de Sandcastle.
La aplicación Sandcastle fue desarrollada por Microsoft para crear un generador de documentación escalable y de alto rendimiento para su documentación API . Microsoft lanzó Sandcastle como una versión Community Technology Preview ( CTP ) en julio de 2006, unos días antes de que NDoc fuera declarado muerto [3] [4] El autor de NDoc, Kevin Downs, citó en un correo electrónico enviado a través de su lista de correo las razones para discontinuar el desarrollo de su popular herramienta como la falta de apoyo de la comunidad, tanto financieramente como en contribuciones al desarrollo, un ataque de bomba de correo automatizado en su dirección de correo electrónico pública y la dirección de la lista de correo NDoc2, y también su impresión de que Sandcastle "se convertirá en el estándar de facto y que NDoc se convertirá lentamente en un recurso secundario estancado".
Sandcastle tuvo un promedio de 217 descargas por día [5] durante el mes de septiembre de 2010, lo que lo convierte en uno de los 25 proyectos más descargados en CodePlex .
El 6 de junio de 2008, el proyecto SandCastle fue eliminado del sitio web de CodePlex [6] después de que un hilo de discusión en el sitio de CodePlex señalara que el código fuente no estaba disponible; a pesar de que CodePlex lo exigía y el proyecto SandCastle se promocionaba como "de código abierto". [7] El 2 de julio, el proyecto regresó a CodePlex y se publicó el código fuente. [8]
.svg/1280px-Free_and_open-source_software_logo_(2009).svg.png){kind=logo}