[Из песочницы] Sandcastle и SHFB
Это статья-заметка о работе с Sandcastle и SHFB, дабы не забыть самому и рассказать другим.Со времён последней статьи о Sandcastle («Создание документации в .NET») прошло 4 года, так что пора освежить некоторые моменты этой утилиты документации.Когда встал вопрос о документации на нашем проекте, то выбор стоял по большей части между Doxygen (который уже использовался в проекте) и Sandcastle (который использовался раньше заказчиком). В итоге выбор пал на Sandcastle, т.к. он был рекомендован самим заказчиком, генерировал схожую визуально документацию, в отличии от Doxygen, а также интеграцией с Help&Manual (интеграция в итоге не использовалась).
Для тех, кому лень гуглить, но интересно посмотреть список других тулзов для документации, вот неплохой список: stackoverflow.com/a/14420174
В упрощённом виде задача из себя представляла генерирование документации в виде ».chm» файла и хелпа на сайте. В качестве примера будет небольшой проект из библиотеки с парой документированных классов и самого Sandcastle проекта (ссылка на гитхаб: github.com/misiam/Sandcastle-Sample).
ИнсталяцияПрежде всего нужно инсталлировать Sandcastle, а если точнее — Sandcastle Help File Builder (SHFB). Это продолжение проекта, который злобно брошен фирмой M$ и заботливо форкнут Eric Woodruff. Качаем отсюда: shfb.codeplex.com/releases/view/121365Мне важны были прежде всего chm-компиллятор и плагин к VS2012 и VS2013. Кроме этого ещё установится, собственно, сам Sandcastle Help File Builder — это приложение, которое позволяет пользоваться интерфейсом, а не прописывать всё в xml-файлах. За исключением тулбара с редактированием текста (жирный, курсив и т.п.) я не нашёл отличий между SHFB и плагином к студии, а студия ещё и автокомплит с интелисенсом предлагает, так что разработку я постепенно перевёл на неё.
Настройка проекта Когда всё установлено, можно добавлять проект в солюшн. В студии в темплейтах появился «Documentation/Sandcastle Help File Builder Project», выбираем его, добавляем «Documentation Sources» (ссылку на проект, который документируем), в проекте включаем «XML documentation file», и запускаем билд. Заходим в папку /bin… и ничего там не находим. Всё дело в том, что по-умолчанию Sandcastle создаёт файлы в папке \Help в проектном фолдере.Чтобы этого избежать, идём в свойства проекта → Path → «Help content output path» и меняем на что-нибудь более привычное, например, на «bin\Help\». После билда можно увидеть LastBuild.log (по умолчанию создаётся в output folder) и chm файл. На внешний вид и предупреждения пока не обращайте внимания.
Теперь хелп создаётся в том фолдере, в котором мы хотели, но хелп должен открываться ещё и с вебки, а chm полноценно поддерживает только explorer, остальные же браузеры в лучшем случае откроют такой хелп с соответствующим плагином. Проще сгенерировать Website: свойства проекта → Build → включаем «Website (HTML/ASP.NET)» (на самом деле там ещё и php есть, удалить можно в post build event. И ещё одна ремарка: build event’ы могут не работать при сборке из студии и SHFB — собирайте через msbuild).
Как только вы добавите Website, вы сможете обнаружить следующую проблему: оба хелпа оказываются в одном фолдере. Ненаглядно, неудобно, и не комильфо. Идём в свойства проекта → Plug-Ins → Output Deployment → Add. Здесь указываем относительные пути для копирования.
Output Deployment plugin
Осталось совсем немного, чтобы привести проект в порядок.
В каталоге Website/html все файлы вида [GUID].htm. Чтобы это исправить заходим в свойства проекта → Help File и меняем свойство «Topic file naming method» с «GUID» на более удобочитаемое «Member name». Теперь адрес в строке браузера будет отражать страницу, на которой находится пользователь.
В тех местах, где отсутствует документация, в хелпе появляются красные предупреждающие надписи «Missing documentation for …».
Такие надписи удобны при разработке, но совершенно неприемлемы в готовой документации. Чтобы их убрать, идём в свойства проекта → Missing Tags и выбираем, какие элементы не должны выдавать сообщения, если у них отсутствует документация. Так же в данный момент используются языки C#, VB, C++, F#. Свойства проекта → Help File → Syntax Filters и выбираем только те языки, которые необходимо.
Создадим пару страничек Для начала удаляем папку Version History со всем содержимым и Welcome.aml страницу из проекта. Структура документации строится именно в файле ContentLayout.content, так что придётся почистить и этот файл.В большинстве случаев при создании новой страницы документации выбирать придётся тип «Conceptual» (типов много и говорить о них можно долго). При создании новой страницы нужно добавить её в ContentLayout. Возможности конфигурации статических страниц относительно сгенерированого кода и друг друга очень большие, вы сможете дерево топиков составить так, как захотите.
Страницы документации ссылаются друг на друга при помощи topic ID. Его можно найти вверху страницы в соответствующем атрибуте.
Пример:
Проблемы начинаются, когда необходимо сослаться на сгенерированные страницы. В этом случае Sandcastle расходится с синтаксисом, который употребляется в метатегах и использует свой:
Список оформления ссылок
Применим к
Правило
Пример
Методы и свойства с аргументами
Необходим список аргументов в скобках
M:Foo.Bar.Func(System.Boolean)
Методы и свойства без аргументов
Скобки не должны быть использованы
M:Foo.Bar.Func
Конструкторы
Используется #ctor вместо имени. Если у конструктора есть параметры, то используется то же правило, что и для метода с параметрами
M:Foo.Bar.#ctor
Статические конструкторы
Используется #сctor вместо имени
M:Foo.Bar.#cctor
Финализаторы
В качестве имени метода используется Finalize
M:Foo.Bar.Finalize
Аргументы
Разделяются запятыми, без пробелов. Используется их имя с неймспейсом. Т.е. вместо int используется System.Int32 и т.д.
M:Foo.Bar.Func(System.Int32,System.String,Foo.Widget)
out и ref параметры
Их имя типа завершается знаком @
M:Foo.Bar.Func(System.Int32@)
Параметры помеченные как params
Нет специальной нотации
Параметры, которые определяют обобщенный тип
Добавляется символ апострофа с номером обобщенного типа
T:Foo.Bar`1
Массивы в качестве параметров
Размерность массива можно опускать
M:Foo.Bar.Func(System.Int32[0:,0:])
Параметры, ссылающиеся на такие типы, как List<>
Используется печерисление через запятую аргументов обобщенного типа, заключенные в фигурные скобки
M:Foo.Bar.Func(System.Collections.Generic.List{System.String})
Оригинал
Список большой, и такие вещи приходится просто знать, тут уж ничего не поделаешь.Хотя можно включить предупреждения «Missing documentation ...» и там можно увидеть, в каком виде Sandcastle ожидает название метода.Tips and Tricks
Существуют разные шаблоны интерфейса: vs2013, vs2010, vs2005, Hana, Prototype. СтОит попробовать как минимум vs2013 и vs2010 — они обе не deprecated, и их поведение отличается. К примеру, в vs2013 после поиска топик открывается в новой вкладке, что у нас на проекте было критично. Также стоит заметить, что на Webhelp можно ссылаться как на Index.aspx, так и на index.html. Часть функционала во втором случае не будет доступна (например, поиск).
Чтобы добавить описание к Namespace, включите в него вот такой класс:
///
То же самое можно сделать и через Sandcastle.
Чтобы добавить описание в топик сгенерированного перегруженного метрода, воспользуйтесь тэгом :
/// O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload
} VisualStudio оставит этот тэг без внимания, а вот Sandcastle добавит его содержимое в документацию.Таблицу таких тегов можно найти по ссылке: Sandcastle«s XML Documentation Comments;
Еще раз ссылка на проект с примерами на github.
