Sandcastle (программное обеспечение) - Sandcastle (software)

замок из песка это генератор документации из Microsoft. Он автоматически производит MSDN -стайл код документации вне отражение информация о Сборки .NET и XML комментарии к документации, найденные в исходный код этих сборок. Его также можно использовать для производства пользовательская документация из Язык разметки Microsoft Assistance (MAML) с тем же внешним видом, что и справочная документация.

Обзор

Sandcastle - это набор командная строка программы, файлы конфигурации, компоненты сборки и XSLT файлы, которые работают вместе для преобразования XML документацию в разделы справки, которые подходят для просмотра в справочной системе. Sandcastle обычно используется для автоматического создания веб-готовых, совместимых с XML HTML документация в одном из трех встроенных стилей представления из сборок .NET и файлов документации XML, которые генерируются компиляторы. Полученные файлы HTML затем используются в качестве входных данных для таких инструментов, как Мастерская HTML-справки создать скомпилированную справку для распространения с соответствующими компьютерная программа.

Sandcastle в настоящее время имеет легкий графический интерфейс пользователя (GUI) в качестве альтернативы MSBuild проект, пакетный сценарий и Windows PowerShell скрипты, которые также предоставляются. Для Sandcastle также доступны несколько инструментов с графическим интерфейсом пользователя, которые предоставляют дополнительные функции и упрощают его использование.^[1]

В Visual Studio SDK на 2005 и 2008 годы включают более старые версии CTP Sandcastle,^[2] хотя последняя версия доступна на GitHub.

Инструменты для песочных замков

Sandcastle состоит из нескольких программ, не все из которых используются в типичном процессе сборки справки. Ниже перечислены наиболее часто используемые инструменты.

• MrefBuilder использует Общая инфраструктура компилятора (CCI) для отражения от управляемых сборок и создания выходного файла.
• XslTransform применяет XSL-преобразования к XML-файлу. Обычно указанный входной файл является файлом, созданным MRefBuilder, или является производным от него.
• BuildAssembler выполняет стек компонентов сборки один раз для каждой темы, определенной в XML-манифесте. Стек компонентов сборки определяется в файле XML с расширением .config. Sandcastle предоставляет несколько компонентов сборки, которые используются в стеках компонентов сборки для выполнения таких задач, как создание индексов данных в памяти, разрешение ссылок, включая общий контент, выполнение преобразований XSL и сохранение окончательного вывода в файл.

Инструменты сообщества

Поскольку в текущем состоянии Sandcastle сам по себе довольно сложен в использовании, люди придумали инструменты и сценарии, которые могут автоматизировать задачу за них. В этом разделе содержится список таких инструментов и скриптов.

• Конструктор файлов справки Sandcastle
• DocProject (Visual Studio 2005/2008)
• Пакетный файл
• Сценарий PowerShell
• Скрипт MSBuild
• Надстройка Sandcastle для Visual Studio
• Инструмент XML-схемы для построителя файлов справки Sandcastle

Выход

Sandcastle создает файлы HTML на основе XML в выбранном стиле представления. (Однако это не означает, что файлы XHTML -соответствует.) HTML определяется файлами преобразования XSL, которые включены в конкретный используемый стиль представления. Сборка обычно использует только один стиль представления за раз.

HTML-файлы, создаваемые Sandcastle, представляют собой концептуальную (пользовательскую) документацию, являющуюся результатом преобразования из Язык разметки Microsoft Assistance (MAML), или это справочная документация, которая автоматически генерируется из данных отражения и комментариев XML-документации. Эти два разных типа вывода HTML используют один и тот же стиль представления и могут быть скомпилированы вместе для создания смешанной пользовательской / справочной документации.

Процессы создания концептуальной документации и справочной документации аналогичны, с одним из основных отличий в том, что концептуальная документация не требует использования программы MRefBuilder.

Концептуальная документация состоит из тем, написанных с использованием схемы типа документа MAML, таких как инструкции, пошаговое руководство, устранение неполадок и ряд других. Sandcastle предоставляет стек концептуальных компонентов сборки (conceptual.config), который разрешает общий контент и ссылки и использует файлы XSL для преобразования элементов MAML в HTML.

Справочная документация создается автоматически для управляемых Интерфейсы прикладного программирования (API) из данных отражения и комментариев документации XML. XSL-преобразование «модель документа», обеспечиваемое выбранным стилем представления, применяется для определения файлов, которые будут созданы. Sandcastle предоставляет стек компонентов эталонной сборки (sandcastle.config), который создает индексы данных в памяти, разрешает совместно используемый контент и ссылки и использует XSL для генерации окончательного вывода HTML.

Скомпилированная справка

Sandcastle не производит скомпилированный вывод справки (хотя создаваемые им файлы HTML могут использоваться в качестве входных данных для компиляторов справки HTML, таких как Мастерская HTML-справки и Справка Microsoft 2 ).

Например, типичный процесс сборки Help 1.x начинается с запуска MrefBuilder.exe для создания файла отражения XML для одной или нескольких сборок. Затем файл отражения обрабатывается средством XslTransform.exe несколько раз для применения различных преобразований XSL, которые добавляют данные, такие как «модель документа» и дополнительную информацию о версии. Затем создается манифест темы на основе XML, который используется программой BuildAssembler.exe, которая создает файлы темы HTML из данных отражения и комментариев документации XML. Основанный на XML оглавление (TOC) файл создается и используется CHMBuilder.exe вместе с файлами HTML, созданными BuildAssembler, для создания Мастерская HTML-справки файлы проекта, индекса и TOC. Наконец, мастерская HTML-справки используется для создания скомпилированного файла справки (.chm).

Некоторые инструменты используются несколько раз в течение одной сборки, например XslTransform и BuildAssembler. В зависимости от требований, другие инструменты и преобразования XSL могут использоваться на различных этапах процесса для изменения вывода Sandcastle.

Фон

Приложение Sandcastle было разработано Microsoft создать масштабируемую и производительную генератор документации для них API документация. Microsoft выпустила Sandcastle как предварительную версию Community Technology (ОСАГО ) в июле 2006 г., за несколько дней до NDoc был объявлен мертвым ^[3][4] Автор NDoc, Кевин Даунс, в электронном письме, разосланном через его список рассылки, назвал причины прекращения разработки его популярного инструмента как отсутствие поддержки сообщества, как финансовой, так и в виде вклада в разработку, автоматизированного почтовая бомба атака на его общедоступный адрес электронной почты и адрес списка рассылки NDoc2, а также его впечатление, что Sandcastle «станет стандартом де-факто, а NDoc постепенно превратится в застойную сторону».

Sandcastle скачивал в среднем 217 загрузок в день. ^[5] в течение сентября 2010 г., что сделало его одним из 25 самых скачиваемых проектов на CodePlex.

6 июня 2008 года проект SandCastle был удален с сайта CodePlex.^[6] после обсуждения на сайте CodePlex указал, что исходный код недоступен; несмотря на то, что CodePlex требует этого, а проект SandCastle рекламируется как «открытый исходный код».^[7] 2 июля проект вернулся на CodePlex, и исходный код был опубликован.^[8]

История

• 29 июля 2006 г. - выпущена версия CTP от июля 2006 г., в которой основное внимание уделялось производительности и масштабируемости. Нет GUI еще не было, приложение не содержало функции для разрешения GAC DLL пока нет.
• 28 августа 2006 г. - выпущена версия CTP от августа 2006 г., ошибки, исправленные в этом выпуске, по всей видимости, в первую очередь связаны с устранением сбоев приложения. HTML вывод приложения теперь совместим с Fire Fox. Некоторые изменения были внесены в интерфейс командной строки.
• 1 октября 2006 г. - была выпущена версия CTP за сентябрь 2006 г., исправления ошибок, по-видимому, в основном сосредоточены на исправлении ошибок в выходных данных и добавлении улучшенной поддержки для некоторых XML теги комментариев.
• 11 ноября 2006 г. - выпущена версия CTP от ноября 2006 г., наряду с исправлениями ошибок, поддерживаются и другие элементы. nDoc теги, а также трансформирует поддержку Fire Fox.
• 10 декабря 2006 г. - выпущена декабрьская версия CTP 2006 г., предоставляющая переменную среды DXROOT, используемую файлами конфигурации, функцию «копирования» API, сквозной HTML и обновления презентации, которые включали поддержку для Fire Fox в стиле VS 2005.
• 6 марта 2007 г. - выпущена версия CTP от марта 2007 г., в которой добавлены 4 новых и удалены 3 преобразования XSL, сценарий пакетной сборки и улучшена производительность.
• 17 марта 2007 г. - выпущена версия CTP Technical Refresh за март 2007 г., в которой исправлена ​​функция «копирования» и ошибка служебной программы, а также включен файл, отсутствующий в ранее выпущенной программе установки.
• 19 июня 2007 г. - выпущена версия CTP от июня 2007 г., MSBuild проект, новая версия Общая инфраструктура компилятора (CCI) механизм отражения, новый стиль представления под названием "VS ORCAS ", новый компонент сборки, новые исполняемые утилиты и ряд других улучшений.
• 27 июня 2007 г. - выпущена версия CTP Refresh от июня 2007 г. с переименованием ранее выпущенной версии "VS ORCAS "стиль представления" в "Hana", чтобы избежать путаницы, поскольку документация Orcas Beta 2 и RTM поставляется в MSDN собирался и дальше строиться в стиле представления VS 2005.
• 1 октября 2007 г. - выпущена версия CTP от сентября 2007 г. с первым появлением инструментов CHMBuilder, VersionBuilder и DBCSFix, а также Windows PowerShell скрипт сборки, обновления стиля презентации (особенно в стиле VS 2005) и без .NET Framework файлы отражения, которые обычно включались в предыдущие установщики.
• 30 октября 2007 г. - выпущена версия CTP за октябрь 2007 г., включая .NET Framework файлы, которые отсутствовали в предыдущем выпуске, новый процесс создания концептуальной документации, требующий Язык разметки Microsoft Assistance (MAML) в качестве входных данных, а также улучшены Fire Fox поддерживать.
• 16 января 2008 г. - выпущена версия Sandcastle 2.4.10115, которая является первой официальной версией Sandcastle, выпущенной в Интернете (RTW), без поддержки CTP. Был предоставлен пример графического интерфейса пользователя (GUI), включая преобразование XSL для Script # и возможность вывода ASP.NET интернет сайт.

Смотрите также

• Сравнение генераторов документации

Рекомендации

внешняя ссылка

• Официальный веб-сайт