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

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

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

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

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

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

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

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

• Конструктор файлов справки Sandcastle
• DocProject (Visual Studio 2005/2008)
• Пакетный файл
• PowerShell-скрипт
• Скрипт MSBuild
• Надстройка Sandcastle Visual Studio
• XML Schema Documenter для 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 "doc model", предоставляемое выбранным стилем представления, применяется для определения файлов, которые будут сгенерированы. Sandcastle предоставляет стек компонентов справочной сборки (sandcastle.config), который создает индексы данных в памяти, разрешает общий контент и ссылки и использует XSL для генерации окончательного вывода HTML.

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

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

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

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

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

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

• 29 июля 2006 г. — выпущена версия CTP июля 2006 г., в которой основное внимание уделялось производительности и масштабируемости. Графический интерфейс пользователя еще не был представлен, приложение еще не содержало функции разрешения 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 г., в которой исправлена ​​функция «риппинг» и ошибка утилиты, а также включен файл, отсутствовавший в ранее выпущенном установщике.
• 19 июня 2007 г. — выпущена версия CTP за июнь 2007 г., включающая проект MSBuild , новую версию движка рефлексии Common Compiler Infrastructure (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 Markup Language (MAML), а также улучшенную поддержку Firefox .
• 16 января 2008 г. — вышла версия Sandcastle 2.4.10115, которая стала первой официальной не-CTP-версией Sandcastle, выпущенной в Интернете (RTW). Был предоставлен пример графического пользовательского интерфейса (GUI), включая преобразование XSL для Script# и возможность вывода веб -сайта ASP.NET .

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

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

• SHFB на GitHub