Sandcastle: генерация документации с диаграммами классов

    В продолжение статьи про автогенерацию документации по XML комментариям .NET кода с помощью Sandcastle я решил немного рассказать про компонент Drawbridge. Он позволяет встраивать в документацию кликабельные диаграммы классов экспортируемые из Visual Studio. Можно жмакнуть по классу и сразу перейти к его описанию. Мелочь, а приятно…


    В предыдущей статье автор рассказал как прикрутить к генератору документации Sandcastle его GUI оболочку для удобного конфигурирования того, что хотим получить в итоге. На этом подробно останавливаться не буду.
    Пусть у нас имеется:
    • Microsoft .NET Framework 3.5
    • Visual Studio 2008 (SP1)
    • Xml-документированный проект, допустим, на C#


    Install.



    Оговорюсь сразу, что все эти приложения я ставил по default директориям, чтобы потом в куче xml конфигов не исправлять пути. Итак:

    1. Качаем и устанавливаем Sandcastle 2.4.10520. Это самый главный «движок» всего ансамбля, который анализирует xml комментарии в коде и анализирует непосредственно сборку, используя .NET Reflection. Из его output потом строится документация (chm, HxS, asp .net).

      После установки Sandcastle «прописывается» через системную переменную окружения:
      DXROOT = “C:\Program Files\Sandcastle\”
    2. Попробуем построить документацию в виде файлика *.chm, поэтому скачаем Microsoft HTML Help Workshop 1.32. Это он будет принимать output из Sandcastle, и выдавать «на блюдечке с голубой каёмочкой» Documentation.chm
    3. Для удобства настройки параметров построения документации (target solution, copyright, feedback email) качаем Sandcastle Help File Builder 1.8.0.2 Beta. Это GUI, в результате работы которого получается xml файл с параметрами построения документации (*.shfbproj). Он впоследствии и подается на вход «генератору» Sandcastle.

      Он тоже пропишется в системных переменных окружения (%SHFB%), поэтому после установки всех «блюстителей ясности кода» желательно будет перезагрузить компьютер.
    4. Для встраивания в документацию кликабельных диаграмм классов используем Drawbridge 2.1.3. Качаем и устанавливаем. Компонент давненько не обновлялся, последний релиз был 26 февраля 2008 года, и автор при его создании использовал несколько сторонних библиотек, поэтому код, к сожалению, закрытый. Но, главное, он работает. =)

      Чтобы подружить Drawbridge со связкой Sandcastle+SHFB, используем уличную магию, подсказанную автором SHFB. В директорию к установленному Sandcastle (C:\Program Files\Sandcastle\ProductionTools) добавляем (создаем) файл BuildAssembler.exe.config с содержимым:

      <?xml version="1.0" encoding="utf-8" ?>
      <configuration>
       <runtime>
         <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> 
           <dependentAssembly>
             <assemblyIdentity name="BuildAssemblerLibrary"
               publicKeyToken="31bf3856ad364e35" culture="neutral"/> 
             <bindingRedirect oldVersion="0.0.0.0-2.4.10520.0" newVersion="2.4.10520.1"/> 
           </dependentAssembly>
         </assemblyBinding>
       </runtime>
      </configuration>

      * This source code was highlighted with Source Code Highlighter.


      Drawbridge наивно полагает, что работать ему предстоит, видимо, в какой-то прежней версии связки Sandcastle+SHFB и потому после установки он просто добавляет объявление своей сборки в одну из директорий SHFB:
      C:\Program Files\EWSoftware\Sandcastle Help File Builder\BuildComponents\drawbridgecomponent.config

      Но SHFB в GUI его не увидит. Поэтому, чтобы Drawbridge зарегистрировать, нужно содержимое этого конфига, между
      <component id="Drawbridge Class Diagram Generator"></component>
      добавить вниз файла:
      C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilder.Components.config


    That’s all.
    Осталось самое интересное: откомментировать проект и сгенерировать документацию.

    Hello, world!



    Наш HelloWorld:
    HelloWorld\sand\HelloWorld.shfbproj Конфиг для генерирования документации, созданный в SHFB
    HelloWorld\src\HelloWorld.sln Solution, сам проектик
    HelloWorld\src\HelloWorld\* Файлы проекта
    HelloWorld\src\HelloWorld\diagram Сюда я сохранял файлы классов диаграмм из Visual Studio (*.cd)
    HelloWorld\src\HelloWorld\drawbridge Сюда я сохранял экспортированные в изображения классы диаграмм (*.jpg)


    Пишем простенький Solution:

    На картинке выше, для класса Program мы указали, что хотим в его описании видеть диаграмму классов «Person.cd».

    Не забываем включать генерацию XML при построении сборки в свойствах проекта, на вкладке Build:



    Теперь, если душа поэта просит нарисовать диаграмму классов в Visual Studio – рисуем встроенными средствами.
    Сохраняем *.cd в HelloWorld\diagram, и одновременно экспортируем все рисунки в *.jpg в HelloWorld\drawbridge. Легко и непринужденно. =)



    Создаем проект построения документации: HelloWorld\sand\HelloWorld.shfbproj, как было описано в предыдущей статье, а в компонентах добавляем «Drawbridge Class Diagram Generator» и соответствующим образом настраиваем его, направляя на папки истинные:



    Generating Documentation.



    Генерация документации протекает с обильным количеством логов. Если ее строим из GUI через SHFB, то выглядит это подобным образом:



    Если операции прошли успешно, то в логах отразятся подобные записи:


    Info: DrawbridgeComponent: Instantiating component.
    Info: DrawbridgeComponent: [CastleApps.Drawbridge.Component, version 2.1.3.0. Copyright © 2008 ..]
    Info: DrawbridgeComponent: Extracting conifiguration from sandcastle.config (success):True

    Merging custom build component configurations
    C:\...\Projects\HelloWorld\sand\Help\Working\sandcastle.config
    Replacing default configuration for 'Code Block Component' with the custom configuration
    Added configuration for 'Drawbridge Class Diagram Generator' after 'Microsoft.Ddue.Tools.TransformComponent' (instance 1)
    No additional help attributes defined. The 'HTML Help 2 Attributes' component was not added.
    Last step completed in 00:00:00.0313

    Info: DrawbridgeComponent: T:TestExample.HelloWorld.Program :class diagrams found = 1
    Info: DrawbridgeComponent: T:TestExample.HelloWorld.Program: found diagram 'person'.
    ...


    Build.



    Если все заработает, то документацию не обязательно строить через интерфейс.
    1. Можно какой-нибудь *.cmd файл напрямую натравить:
      msbuild.exe HelloWorld.shfbproj
    2. <!-- DependsOnTargets="BuildCode" -->
      <Target Name="BuildDocumentation" >
        <!-- Build source code docs -->
        <MSBuild Projects="$(SandPath)\HelloWorld.shfbproj"
             Properties="Configuration=Debug;Platform=AnyCPU;OutDir=$(Help)" />
      </Target>

      * This source code was highlighted with Source Code Highlighter.


    Finally.



    Кликабельная диаграмма классов в документации будет выглядеть как ниже на картинке. Тыцкнув на интересный нам класс, мы тут же переходим на соответствующую страницу документации. Приятно. =)



    Или даже в виде asp страничек:



    P.S.
    Накручивая такие бигуди, становится приятно от того, что избавиться от всего этого можно в пару кликов, не задевая комментарии кода. Разве что перестанут работать:
    /// <img src="ClassDiagram.cd" />
    Так почему бы не попробовать?

    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 3

      0
      Спасибо за статью. Документация становится все удобнее и полнее.

      Только вот уточнение: а зачем руками экспортировать диаграмму в jpg, ведь указывается потом в XML комментарии *.cd файл?
        +1
        В документации к Drawbridge автор явно написал: «Class diagrams need to be exported as Jpeg images before the Drawbridge component can integrate the diagrams with the documentation.» Пока самостоятельно выдергивать jpg, видимо, Drawbridge не приучен.

        На этот счет на stackoverflow есть неплохая заметка, которая ведет на блог msdn. =)
        0
        Картинка у вас слетела.

        Only users with full accounts can post comments. Log in, please.