Skip to content

Latest commit

 

History

History
134 lines (116 loc) · 13.7 KB

sandcastle.md

File metadata and controls

134 lines (116 loc) · 13.7 KB
Raw

Это статья-заметка о работе с Sandcastle и SHFB, дабы не забыть самому и рассказать другим.

Со времён последней статьи о Sandcastle (http://habrahabr.ru/post/102177/) прошло 4 года, так что пора освежить некоторые моменты этой утилиты документации. Когда встал вопрос о документации на нашем проекте, то выбор стоял по большей части между Doxygen(который уже использовался в проекте), и Sandcastle (который использовался раньше заказчиком). В итоге выбор пал на Sandcastle, т.к. он был рекомендован самим заказчиком, генерировал схожую визуально документацию, в отличии от Doxygen, а также интеграцией с Help&Manual (интеграция в итоге не использовалась).

Для тех, кому лень гуглить, но интересно посмотреть список других тулзов для документации, вот неплохой список: http://stackoverflow.com/a/14420174

В упрощённом виде задача из себя представляла генерирование документации в виде ".chm" файла и хелпа на сайте. В качестве примера будет небольшой проект, из библиотеки с парой документированных классов и самого Sandcastle проекта (ссылка на гитхаб: https://github.com/misiam/Sandcastle-Sample).

Install

Прежде всего нужно инсталлировать Sandcastle, а если точнее то Sandcastle Help File Builder (SHFB) - это продолжение проекта, который злобно брошен фирмой M$ и заботливо форкнут Eric Woodruff. Качаем отсюда: http://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. Здесь указываем относительные пути для копирования.

Осталось совсем немного, чтобы привести проект в порядок. В каталоге 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 расходится с синтаксисом, который употребляется в метатегах и использует свой: M:SandcastleSample.Samples.ConstructorsSamples.#ctor(System.String,System.Int32) M:SandcastleSample.Samples.MethodsSamples.MethodWithRefParameter(System.String,System.String@)

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, включите в него вот такой класс: ///Namespace summary /// internal class NamespaceDoc { //EMPTY } То же самое можно сделать и через Sandcastle.
  • Чтобы 
        </li>