Sandcastle и SHFB

в 12:49, , рубрики: .net, SHFB, документация, Программирование

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» и меняем на что-нибудь более привычное, например, на «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. Здесь указываем относительные пути для копирования.

Output Deployment plugin

Sandcastle и SHFB

Осталось совсем немного, чтобы привести проект в порядок.

В каталоге Website/html все файлы вида [GUID].htm. Чтобы это исправить заходим в свойства проекта -> Help File и меняем свойство «Topic file naming method» с «GUID» на более удобочитаемое «Member name». Теперь адрес в строке браузера будет отражать страницу, на которой находится пользователь.

В тех местах, где отсутствует документация, в хелпе появляются красные предупреждающие надписи «Missing documentation for ...».

Sandcastle и SHFB

Такие надписи удобны при разработке, но совершенно неприемлемы в готовой документации. Чтобы их убрать, идём в свойства проекта -> 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

Источник


* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js