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

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

• 1 Обзор
• 2 Инструменты Sandcastle
• 3 Инструменты сообщества
• 4 Вывод
• 5 Скомпилированная справка
• 6 Предпосылки
• 7 История
• 8 См. Также
• 9 Ссылки
• 10 Внешние ссылки

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

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

Visual Studio SDK для 2005 и 2008 годов включают более старые версии CTP Sandcastle, хотя последний выпуск доступен на 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 Help File Builder

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

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

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

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

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

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

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

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

Приложение Sandcastle было разработано Microsoft для создания масштабируемого и производительного генератора документации для их документации по API. Microsoft выпустила Sandcastle как версию Community Technology Preview (CTP ) в июле 2006 года, за несколько дней до того, как NDoc был объявлен мертвым Автор NDoc, Кевин Даунс, цитируется в электронном письме, отправленном через его список рассылки причины прекращения разработки его популярного инструмента: отсутствие поддержки сообщества, как финансовой, так и в виде вклада в разработку, автоматическая атака mail-bomb на его общедоступный адрес электронной почты и адрес списка рассылки NDoc2, а также также его впечатление, что Sandcastle «станет стандартом де-факто, и что NDoc постепенно превратится в застойную боковую воду».

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

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

• 29 июля 2006 г. - выпущена версия CTP за июль 2006 г., эта версия в основном ориентирована на производительность и масштабируемость. GUI еще не присутствовал, приложение еще не содержало функции для разрешения GAC DLL.
• 28 августа 2006 г. - выпущена версия CTP от августа 2006 г., Ошибки, исправленные в этом выпуске, в первую очередь предназначены для устранения сбоев приложения. HTML вывод приложения теперь совместим с Firefox. Некоторые изменения были внесены в интерфейс командной строки.
• 1 октября 2006 г. - была выпущена версия CTP за сентябрь 2006 г., исправления ошибок, по-видимому, в основном сосредоточены на исправлении ошибок в выводе и добавлении улучшенной поддержки для некоторых Теги комментариев XML.
• 11 ноября 2006 г. - выпущена версия CTP за ноябрь 2006 г., наряду с исправлениями ошибок, другие поддерживаемые элементы - это несколько тегов nDoc, а также преобразования поддержка Firefox.
• 10 декабря 2006 г. - выпущена версия CTP за декабрь 2006 г., предоставляющая переменную среды DXROOT, используемую файлами конфигурации, функцию «копирования» API, сквозной HTML и обновления презентации, которые включали поддержку для Firefox в стиле VS 2005.
• 6 марта 2007 г. - выпущена версия CTP от марта 2007 г., в которой добавлены 4 новых и удалены 3 преобразования XSL, сценарий пакетной сборки и улучшена производительность.
• 17 марта 2007 г. - выпущена версия CTP Technical Refresh за март 2007 г., в которой исправлена ​​функция копирования и служебная программа b ug, и включая файл, который отсутствовал в ранее выпущенном установщике.
• 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, которые были обычными y включены в предыдущие установщики.
• 30 октября 2007 г. - выпущена версия CTP за октябрь 2007 г., включая файлы .NET Framework, которые отсутствовали в предыдущем выпуске, новая концептуальная сборка документации процесс, требующий в качестве входных данных тем Microsoft Assistance Markup Language (MAML), а также улучшенная поддержка Firefox.
• 16 января 2008 г. - была выпущена версия Sandcastle 2.4.10115, являясь первой официальной версией Sandcastle, не поддерживающей CTP, выпущенной в Интернете (RTW). Был предоставлен пример графического пользовательского интерфейса (GUI), включая преобразование XSL для сценария № и возможность вывода веб-сайта ASP.NET.

• Портал бесплатного программного обеспечения с открытым исходным кодом

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

• Официальный сайт