Feel Good.

26 марта 2010

Sandcastle - генерируем документацию

В предыдущей статье, я рассказал о возможностях XML-документации и привел простой пример XML-документирования исходного кода, теперь пора научиться получать заветную документацию в удобном для чтения виде, разумеется, генерировать документацию будем автоматическими средствами Sandcastle.

Для начала, создадим новый проект и добавим в него, заготовленный в предыдущей статье, исходный код, после чего соберем проект с флагом /doc:XMLDoc.xml (или Visual Studio в свойствах проекта "Properties -> Build -> Output" ставим галочку "XML documentation file". После успешной сборки проекта, в выходной папке будет находиться файл XML-документации следующего содержания:


<?xml version="1.0"?>

<doc>

    <assembly>

        <name>CommentTest</name>

    </assembly>

    <members>

        <member name="M:XMLCommentTest.Program.Factorial(System.Int32)">

            <summary>

            <para>

            Вычисляет факториал числа.

            </para>

            </summary>       

            <param name="number">Неотрицательное число.</param>

            <exception cref="T:System.ArgumentOutOfRangeException">

            Если <paramref name="number"/> отрицательное число.

            </exception>

            <exception cref="T:System.OverflowException">

            Если значение факториала слишком велико для типа <see cref="T:System.Decimal"/>.

            </exception>

            <returns>Значение факториала.</returns>

            <example>Простой пример, для <see cref="M:XMLCommentTest.Program.Factorial(System.Int32)"/>.

            <code>

            class Program

            {

                static void Main(string[] args)

                {

                    Console.WriteLine(Factorial(5));

                }

            }

            </code>

            </example>

            <seealso cref="T:System.Math"/>      

            <remarks>

            Вычисление факториала для больших значений <paramref name="number"/>

            может быстро привести к переполнению.

            </remarks>       

        </member>

    </members>

</doc>


Заметьте, что любое упоминание типа или члена происходит полным именем [Имя пространства имен].[Имя типа или члена], хотя явно мы этого не указывали:

cref="T:System.ArgumentOutOfRangeException"

name="M:XMLCommentTest.Program.Factorial(System.Int32)"


На данном этапе мы получили XML-документацю проекта, осталось перегнать ее в формат, удобный для чтения. Конечно, мы можем сами написать свой XSLT для отображения нашей документации в любом виде. Классическая задача XML+XSLT

Но в нашем случае, это стандартная задача, для которой можно обойтись стандартными средствами. На сегодняшний день существуют несколько бесплатных систем автоматического получения технической документации: Sandcastle, NDoc и другие, но безусловным лидером является Sandcastle. Его и рассмотрим.

Если коротко о Sandcastle, то можно сказать что он генерирует готовый CHM-файл с полной навигацией (как локальной так и с ссылками на внешний MSDN), разделами и фильтрами поиска по документации для указанной сборки/xml-документации (более подробно о возможностях можно узнать здесь).
Устанавливается Sandcastle с помощью install-файла, скачать который можно с официального сайта. Я советую также скачать GUI-надстройку Sandcastle Help File Builder.

Приступаем к работе, устанавливаем скаченный софт в следующем порядке: сначала Sandcastle далее Sandcastle Help File Builder, после чего проверьте(echo %DXROOT%) переменную окружения DXROOT, в ней должен находиться путь к Sandcastle. Далее открываем Sandcastle Help File Builder, и видим, что окно Sandcastle Help File Builder состоит из двух областей: Project Properties и Project Explorer. Добавляем в окне "Project Explorer" путь к нашей сборке/xml-документации, тем самым указав сборку, для которой будем генерировать документацию. Процесс генерации можно настроить, для этого в окне "Project Properties" содержатся следующие разделы:

  1. Build - отвечает за сборку: формат документации, версия .net, лог-файл и другие.
  2. Comments - общие комментарии.
  3. Help file - настраивает содержимое документации: копирайт, footer/header-ы, заголовки, стиль представления, ссылки и прочие.
  4. Path - задает рабочие пути: выходная директория, директория Sandcastle и другие.
  5. Show Missing Tag - показывать ли предупреждение, если пропущен документирующий тэг.
  6. Visibility - задает фильтр того, что попадет в документацию.
Выставив необходимых свойства, сохраните файл проекта (*.shfbproj) и запустите Build (через меню или комбинацией клавиш "CTRL-SHIFT-B"). Если Вы все правильно сделали, то в выходной директории (по-умолчению это .\Help\) увидите собранный файл документации (по-умолчанию Documentation.chm) и лог файл. Документация готова!

Дополнение:
Q: "А как же диаграммы классов? Можно ли их встраивать в документацию?"
A: "Да, можно! Например, использовать компонент Drawbridge"

7 комментариев:

  1. к сожалению Sandcastle больше не развивается

    ОтветитьУдалить
  2. Нашел сравнительную таблицу автоматических генераторов документации:
    http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

    ОтветитьУдалить
  3. @Сергей

    Но его все еще достаточно для создания грамотного API Reference


    P.S.
    Не удается писать комментарии через OpenID - возникаеь какая-то ошибка "Не удалось проверить учетные данные OpenID"

    ОтветитьУдалить
  4. @dip_the_coder

    Спасибо за выявленную ошибку с OpenID. Пока не знаю как, но постараюсь исправить.

    ОтветитьУдалить
  5. добрый день, спасибо за статью (на первой странице в гугле по запросу "SandCastle")

    и вопрос - то что у меня оно тестовое приложение с формой 2мя кнопками обрабатывало 27 мин. - это так и надо, или что-то не так?
    потом запустил для ClassLibrary - справилось за 5 минут.

    версия не самая последняя, 2009 года, SandCastle Help File Builder 1.8.0.2

    ОтветитьУдалить
  6. @dwarwood
    Да, компиляция происходит довольно долго. Все зависит от выбранных опций. У меня тогда этот пример собрался за ~2 мин. Обычно я выбираю минимум опций, да и генерирую документацию не так часто.

    ОтветитьУдалить
  7. ага. спасибозаответ.

    ОтветитьУдалить