Sandcastle es un generador de documentación de Microsoft . Genera automáticamente documentación de código estilo MSDN a partir de la información reflejada de los ensamblajes .NET y los comentarios de la 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.
Desarrollador (es) | Microsoft |
---|---|
Versión inicial | 2006 |
Lanzamiento estable | 2.6.10621.1 / 23 de junio de 2010 |
Repositorio | github |
Escrito en | C# |
Sistema operativo | Microsoft Windows |
Plataforma | .NET Framework |
Tipo | Generador de documentación |
Licencia | Licencia pública de Microsoft |
Sitio web | github |
Descripción general
Sandcastle es un conjunto de programas de línea de comandos , archivos de configuración, componentes de compilación y archivos XSLT que funcionan juntos para convertir la documentación basada en XML en temas de ayuda que se pueden ver en un sistema de ayuda. Sandcastle generalmente se usa para generar automáticamente documentación HTML lista para web y compatible con XML en uno de los tres estilos de presentación integrados de ensamblajes .NET y archivos de documentación XML que son generados por compiladores . Los archivos HTML resultantes se utilizan luego como entrada para herramientas como el HTML Help Workshop para producir ayuda compilada para su distribución con el programa informático correspondiente .
Sandcastle cuenta actualmente 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. Varias herramientas de GUI de la comunidad también están disponibles para Sandcastle, que brindan características 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 .
Herramientas de castillos de arena
Sandcastle consta de varios programas, no todos los cuales se utilizan en el proceso típico de creación de ayuda. Las herramientas de uso común se enumeran a continuación.
- MrefBuilder usa Common Compiler Infrastructure (CCI) para reflejar los ensamblados administrados y generar un archivo de salida.
- XslTransform aplica transformaciones XSL a un archivo XML. Normalmente, el archivo de entrada especificado es o se deriva de un archivo generado por MRefBuilder.
- BuildAssembler ejecuta una pila de componentes de compilación, una vez por cada tema definido en un manifiesto XML. Una pila de componentes de compilación se define en un archivo XML con una extensión .config. Sandcastle proporciona varios componentes de compilación que se utilizan en pilas de componentes de compilación para realizar tareas como generar índices de datos en memoria, resolver enlaces, incluido el contenido compartido, ejecutar transformaciones XSL y guardar la salida final en un archivo.
Herramientas comunitarias
Debido a que en su estado actual, Sandcastle por sí solo es bastante complejo de usar, la gente ha creado herramientas y scripts que pueden automatizar la tarea para ellos. Esta sección contiene una lista de dichas herramientas y scripts.
Producción
Sandcastle produce archivos HTML basados en XML en un estilo de presentación elegido. (Sin embargo, esto no significa 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 está utilizando. Una compilación normalmente usa 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 los temas de Microsoft Assistance Markup Language (MAML), o son 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 pueden compilarse juntos para producir documentación de referencia / usuario mixta.
Los procesos para construir la documentación conceptual y la documentación de referencia son similares, con una de las principales diferencias es 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 cómo, guía, solución de problemas y varios otros. Sandcastle proporciona una pila de componentes de construcción conceptual (conceptual.config) que resuelve el contenido compartido y los enlaces, 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 los datos de reflexión y los comentarios de la 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 construcción de referencia (sandcastle.config) que crea índices en memoria de los datos, resuelve el contenido compartido y los enlaces, y usa XSL para generar la salida HTML final.
Ayuda compilada
Sandcastle no produce la salida de ayuda compilada por sí misma (aunque los archivos HTML que produce se pueden utilizar como entrada para compiladores de ayuda HTML como HTML Help Workshop y Microsoft Help 2 ).
Por ejemplo, el proceso de compilación de Help 1.x típico comienza ejecutando MrefBuilder.exe para producir un archivo de reflexión XML para uno o más ensamblados. Luego, 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, el programa BuildAssembler.exe genera y utiliza un manifiesto de tema basado en XML, que genera archivos de tema HTML a partir de los datos de reflexión y los comentarios de la documentación XML. Un basado en XML tabla de contenido de archivos (TOC) es generada y utilizada por CHMBuilder.exe, junto con los archivos HTML producidos por BuildAssembler, para generar HTML Help Workshop archivos de proyecto, índice y TOC. Finalmente, el taller de ayuda HTML se utiliza para generar un archivo de ayuda compilado (.chm).
Algunas herramientas se utilizan varias veces durante una sola compilación, como XslTransform y BuildAssembler. Dependiendo de los requisitos, se pueden usar otras herramientas y transformaciones XSL en varias etapas durante el proceso para modificar la salida de Sandcastle.
Fondo
La aplicación Sandcastle fue desarrollada por Microsoft para crear un generador de documentación escalable y eficaz para su documentación API . Microsoft lanzó Sandcastle como una versión de 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 descontinuar desarrollo de su popular herramienta como una falta de apoyo de la comunidad, tanto financieramente como como contribuciones de desarrollo, un ataque automatizado con bomba de correo en su dirección de correo electrónico público 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 agua lateral estancada ".
Sandcastle promedió 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 requiere y el proyecto SandCastle se promociona como "código abierto". [7] El 2 de julio, el proyecto volvió a CodePlex y se publicó el código fuente. [8]
Historia
- 29 de julio de 2006: se lanzó la versión CTP de julio de 2006, esta versión se centró principalmente en el rendimiento y la escalabilidad. Sin GUI estaba presente, sin embargo, la solicitud no contenía una característica para resolver GAC DLL todavía.
- 28 de agosto de 2006: se lanzó la versión CTP de agosto de 2006, los errores corregidos en esta versión parecen principalmente para corregir fallas de la aplicación. La salida HTML de la aplicación ahora es compatible con Firefox . Se realizaron algunos cambios en la interfaz de línea de comandos.
- 1 de octubre de 2006: se lanzó la versión CTP de septiembre de 2006, las correcciones de errores parecen centrarse principalmente en corregir errores en la salida y agregar un mejor soporte para algunas etiquetas de comentarios XML .
- 11 de noviembre de 2006: se lanzó la versión CTP de noviembre de 2006, junto con correcciones de errores, otros elementos que se admiten son algunas etiquetas nDoc , y las transformaciones también son compatibles con Firefox .
- 10 de diciembre de 2006: se lanzó la versión CTP de diciembre de 2006, que proporciona una variable de entorno DXROOT utilizada por los archivos de configuración, una función de "extracción" de API, HTML de paso a través y actualizaciones de presentación que incluyen compatibilidad con Firefox en el estilo VS 2005.
- 6 de marzo de 2007: se lanzó la versión CTP de marzo de 2007, que agrega 4 transformaciones XSL nuevas y elimina 3, un script de compilación por lotes y mejoras de rendimiento.
- 17 de marzo de 2007: se lanzó la versión de actualización técnica de CTP de marzo de 2007, que corrigió la función de "extracción" y un error de utilidad, e incluyó un archivo que faltaba en el instalador publicado anteriormente.
- 19 de junio de 2007: se lanzó la versión CTP de junio de 2007, que proporciona un proyecto MSBuild , una nueva versión del motor de reflexión Common Compiler Infrastructure (CCI), un nuevo estilo de presentación denominado "VS ORCAS ", un nuevo componente de compilación, un nuevo ejecutable utilidades y varias otras mejoras.
- 27 de junio de 2007: se lanzó la versión CTP Refresh de junio de 2007, que cambió el nombre del estilo de presentación "VS ORCAS " publicado anteriormente a "Hana" para evitar confusiones, ya que el envío de documentación de Orcas Beta 2 y RTM en MSDN se seguiría incorporando. el estilo de presentación VS 2005.
- 1 de octubre de 2007: se lanzó la versión CTP de septiembre de 2007, con la primera aparición de las herramientas CHMBuilder, VersionBuilder y DBCSFix, un script de compilación de Windows PowerShell , actualizaciones de estilo de presentación (más notablemente al estilo VS 2005) y sin .NET Archivos de reflexión de framework que normalmente se incluían en instaladores anteriores.
- 30 de octubre de 2007: se lanzó la versión CTP de octubre de 2007, incluidos los archivos de .NET Framework que faltaban en la versión anterior, un nuevo proceso de creación de documentación conceptual que requiere los temas de Microsoft Assistance Markup Language (MAML) como entrada y también una mejor compatibilidad con Firefox .
- 16 de enero de 2008: se lanzó la versión Sandcastle 2.4.10115, siendo la primera versión oficial no CTP de Sandcastle lanzada a la web (RTW). Se proporcionó un ejemplo de interfaz gráfica de usuario (GUI), incluida una transformación XSL para Script # y la opción de generar un sitio web ASP.NET .
Ver también
- Comparación de generadores de documentación
Referencias
- ^ Ayuda del castillo de arena
- ^ Anuncio de castillo de arena: blog de castillo de arena
- ^ Sandcastle - Microsoft CTP de un generador de archivos Help CHM sobre las colas de la muerte de NDoc
- ^ NDoc 2 está oficialmente muerto
- ^ Estadísticas del castillo de arena
- ^ Proyecto de castillo de arena eliminado del Codeplex
- ^ "¿Castillo de arena 'código abierto'?" . Consultado el 2 de julio de 2008 .
- ^ "Código fuente de castillo de arena publicado en Codeplex" . 2008-07-02 . Consultado el 2 de julio de 2008 .
enlaces externos
- Página web oficial