Это статья-заметка о работе с 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» и меняем на что-нибудь более привычное, например, на «binHelp». После билда можно увидеть 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. Здесь указываем относительные пути для копирования.
Осталось совсем немного, чтобы привести проект в порядок.
В каталоге 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. Его можно найти вверху страницы в соответствующем атрибуте.
Пример:
<link xlink:href="b2ac2359-2794-4644-b900-297937ffeaae" />
Проблемы начинаются, когда необходимо сослаться на сгенерированные страницы. В этом случае Sandcastle расходится с синтаксисом, который употребляется в метатегах <see /> и использует свой:
<codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.ConstructorsSamples.#ctor(System.String,System.Int32)</codeEntityReference>
<codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.MethodsSamples.MethodWithRefParameter(System.String,System.String@)</codeEntityReference>
qualifyHint устанавливается в «true», если нужно показывать сигнатуру метода.
| Применим к | Правило | Пример |
|---|---|---|
| Методы и свойства с аргументами | Необходим список аргументов в скобках | 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, включите в него вот такой класс:
///<summary>Namespace summary</summary> ///<include file='_Namespace.xml' path='Documentation/*' /> internal class NamespaceDoc { //EMPTY }То же самое можно сделать и через Sandcastle.
- Чтобы добавить описание в топик сгенерированного перегруженного метрода, воспользуйтесь тэгом :
/// <summary> /// Go to overload <see cref="O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload"/> /// <example> /// <para>To link to both overloads use 'O': <code>O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload</code></para> /// </example> /// </summary> /// <overloads> /// <para>'overloads' tag used in Sandcastle to put some additional inforation to "Ovetrload methods" page in the documentation.</para> /// </overloads> /// <param name="param"></param> public void MethodWithOverload(string param) { }VisualStudio оставит этот тэг без внимания, а вот Sandcastle добавит его содержимое в документацию.
Таблицу таких тегов можно найти по ссылке: Sandcastle’s XML Documentation Comments;
Еще раз ссылка на проект с примерами на github.
Автор: Misiam
