В продолжение статьи про автогенерацию документации по XML комментариям .NET кода с помощью Sandcastle я решил немного рассказать про компонент Drawbridge. Он позволяет встраивать в документацию кликабельные диаграммы классов экспортируемые из Visual Studio. Можно жмакнуть по классу и сразу перейти к его описанию. Мелочь, а приятно…В предыдущей статье автор рассказал как прикрутить к генератору документации Sandcastle его GUI оболочку для удобного конфигурирования того, что хотим получить в итоге. На этом подробно останавливаться не буду.
Пусть у нас имеется:
- Microsoft .NET Framework 3.5
- Visual Studio 2008 (SP1)
- Xml-документированный проект, допустим, на C#
Install.
Оговорюсь сразу, что все эти приложения я ставил по default директориям, чтобы потом в куче xml конфигов не исправлять пути. Итак:
- Качаем и устанавливаем Sandcastle 2.4.10520. Это самый главный «движок» всего ансамбля, который анализирует xml комментарии в коде и анализирует непосредственно сборку, используя .NET Reflection. Из его output потом строится документация (chm, HxS, asp .net).
После установки Sandcastle «прописывается» через системную переменную окружения:
DXROOT = “C:\Program Files\Sandcastle\” - Попробуем построить документацию в виде файлика *.chm, поэтому скачаем Microsoft HTML Help Workshop 1.32. Это он будет принимать output из Sandcastle, и выдавать «на блюдечке с голубой каёмочкой» Documentation.chm
- Для удобства настройки параметров построения документации (target solution, copyright, feedback email) качаем Sandcastle Help File Builder 1.8.0.2 Beta. Это GUI, в результате работы которого получается xml файл с параметрами построения документации (*.shfbproj). Он впоследствии и подается на вход «генератору» Sandcastle.
Он тоже пропишется в системных переменных окружения (%SHFB%), поэтому после установки всех «блюстителей ясности кода» желательно будет перезагрузить компьютер. - Для встраивания в документацию кликабельных диаграмм классов используем 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.
Если все заработает, то документацию не обязательно строить через интерфейс.
- Можно какой-нибудь *.cmd файл напрямую натравить:
msbuild.exe HelloWorld.shfbproj <!-- 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" />