Песчаный замок (программное обеспечение)

Замок из песка
Разработчик(и)	Майкрософт
Первоначальный выпуск	2006 год ; 18 лет назад
Стабильная версия	2.6.10621.1 / 23 июня 2010 г .; 14 лет назад
Репозиторий	github .с /EWSoftware /ШФБ
Написано в	С#
Операционная система	Microsoft Windows
Платформа	.NET Framework
Тип	Генератор документации
Лицензия	Публичная лицензия Майкрософт
Веб-сайт	ewsoftware .github .что /ШФБ /

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

Обзор

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

В настоящее время 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 создает 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-справки, таких как 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 используется для создания скомпилированного файла справки (.chm).

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

Фон

Приложение Sandcastle было разработано Microsoft для создания масштабируемого и производительного генератора документации для документации API . Microsoft выпустила Sandcastle как версию Community Technology Preview ( CTP ) в июле 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 г., эта версия в основном ориентирована на производительность и масштабируемость. еще не Графического интерфейса было, приложение еще не содержало функции разрешения библиотек 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 за март 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 . Файлы отражения платформы , которые обычно включались в предыдущие установщики.
30 октября 2007 г. — была выпущена версия CTP за октябрь 2007 г., включающая файлы .NET Framework , отсутствовавшие в предыдущем выпуске, новый процесс построения концептуальной документации, требующий в качестве входных данных тем Microsoft Assistance Markup Language (MAML), а также улучшенная Firefox. поддержка .
16 января 2008 г. — была выпущена версия Sandcastle 2.4.10115, ставшая первой официальной версией Sandcastle, не являющейся CTP, выпущенной в Интернете (RTW). Был предоставлен пример графического пользовательского интерфейса (GUI), включая преобразование XSL для Script# и возможность вывода веб-сайта ASP.NET .

См. также

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

Ссылки

^ Помощь Песчаному замку
^ Анонс Sandcastle: блог Sandcastle
^ Sandcastle - Microsoft CTP генератора файлов справки CHM после смерти NDoc
^ NDoc 2 официально мертв
^ Статистика Песчаного замка
^ Проект Sandcastle удален из Codeplex.
^ «Замок из песка с открытым исходным кодом»? . Проверено 2 июля 2008 г.
^ «Исходный код Sandcastle опубликован в Codeplex» . 2 июля 2008 г. Проверено 2 июля 2008 г.

Внешние ссылки

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

ШФБ на GitHub

[1] Помощь Песчаному замку

[2] Анонс Sandcastle: блог Sandcastle

[3] Sandcastle - Microsoft CTP генератора файлов справки CHM после смерти NDoc

[4] NDoc 2 официально мертв

[5] Статистика Песчаного замка

[6] Проект Sandcastle удален из Codeplex.

[7] «Замок из песка с открытым исходным кодом»? . Проверено 2 июля 2008 г.

[8] «Исходный код Sandcastle опубликован в Codeplex» . 2 июля 2008 г. Проверено 2 июля 2008 г.

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]