Sandcastle Help File Builder – это графическая оболочка над генератором документации Sandcastle. В свою очередь, Sandcastle – это гибкий и многофункциональный генератор документации для .Net с использованием XML комментариев из исходного кода. Воспользуемся этим и в несколько шагов создадим документацию нашего проекта.
Основные возможности Sandcastle
- Включение в документацию XML комментариев из исходного кода.
- Автоматическое получение информации об элементах .Net, таких как классы, методы, свойства, перечисления с помощью reflection.
- Возможность интегрировать свои дополнительные HTML страницы в документацию.
- Генерация документации в нескольких форматах: Microsoft Compiled HTML Help (CHM), MS Microsoft Help 2 (MSDN), веб-сайт — статический и динамический с поиском (ASP.NET).
Подготовка к работе
Для создания документации нам необходимо установить последние стабильные версии:
Тестовый проект для документирования
В моем случае не буду усложнять пример и сделаю документацию для приложения «Hello World!». Документация будет содержать описание используемых классов, пространств имен, стартовую страницу и страницу дополнительной информации о приложении.
Наш главный класс консольного приложения:
using System;
using System.Text;
namespace Atv.Research.HelloWorld
{
/// <summary>
/// Базовый класс тестового приложения
/// </summary>
public class Program
{
/// <summary>
/// Стартовый метод консольного приложения
/// </summary>
/// <param name="args">Аргументы консольного приложения</param>
public static void Main(string[] args)
{
Console.Out.WriteLine("Hello World!");
}
}
}
* This source code was highlighted with Source Code Highlighter.В свойствах проекта необходимо выставить генерацию XML файла с нашими комментариями. Для этого в контекстном меню на проекте Properties/вкладка Build/раздел Output – выставите галочку для «XML documentation file». После компиляции проекта мы получим наше приложение Atv.Research.HelloWorld.exe и файл с комментариями Atv.Research.HelloWorld.XML.
Давайте сразу добавим в нашу документацию пару статических страниц. Очень часто бывает, что технической информации из кода недостаточно. Нужны более общие описания, с рисунками и диаграммами. Или, например, требуется вставить целиком текст конфигурационного файла или WSDL для веб-сервиса. В качестве примера мы вставим 2 статические HTML страницы. Одна из них будет стартовой для нашей документации.
Index.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- @DefaultTopic -->
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>About</title>
</head>
<body>
<div style="height:140px;"> </div>
<div style="text-align:center">
<h1>Тестовое консольное приложение<br />Hello World!</h1>
<div><a href="Details.htm">Детальное описание</a></div>
</div>
</body>
</html>
* This source code was highlighted with Source Code Highlighter.Details.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>Details</title>
</head>
<body>
<h2>Назначение</h2>
<p>Тестовое консольное приложение "Hello World" предназначено для демонстрации возможностей Sandcastle.</p>
<h2>Пример ссылок на автодокументацию</h2>
В качестве примера в консольное приложение добавлен следующий тестовый класс: <see cref="Atv.Research.HelloWorld.MyTestClass"/>
<h2>Пример использования подсветки синтаксиса с использованием встроенного компонента "The Code Block Component"</h2>
<pre lang="cs" numberLines="true" outlining="true"
title="Example of Syntax Highlighting">
// Test method
public void TestMethod(string s, int x)
{
// Debug code
x = x + 1;
s = x.ToString();
Console.WriteLine("The string = " + s);
}
</pre>
</body>
</html>
* This source code was highlighted with Source Code Highlighter.Здесь следует обратить внимание на следующее:
- @DefaultTopic — комментарий используется для того, что бы указать на то, что эта страница будет стартовой.
- Тег <see> — поможет сослаться со статической страницы на страницу автоматически генерируемой документации по исходным кодам, содержащей конкретный класс, метод или пространство имен.
- Тег <pre> — сделает подсветку синтаксиса в примерах кода для статических страниц.
Запуск программы
Собственно, входные данные у нас уже есть. Это наше приложение, XML файл с комментариями и 2 статические страницы для описания нашего приложения. Пришло время запускать «Sandcastle Help File Builder GUI».
Главное окно программы «Sandcastle Help File Builder GUI»
- Добавляем наши сборки и XML файлы с документацией, в нашем случае это Atv.Research.HelloWorld.exe и Atv.Research.HelloWorld.XML.
- Добавляем общее описание проекта.
- Добавляем описание пространств имен, правильно структурированные и описанные – они помогают лучше ориентироваться в проекте. Вся эта информация будет отражена в полученной документации.
- Выполняем настройки проекта. Я перечислю только обязательные и те, на которые стоит сразу обратить внимание.
Дополнительно вы можете настроить текст, который будет выводиться на каждой странице вверху и внизу, строку копирайта и ссылки для обратной связи. Указать, стоит ли документировать приватные и защищенные методы и свойства. Включить показ предупреждений при отсутствии XML комментария в коде. Подробное описание настроек вы всегда найдете в прилагающейся документации. Но и не забывайте, что «Sandcastle Help File Builder» — это графическая надстройка над Sandcastle, и вы можете при необходимости использовать его напрямую.Параметр Значение Описание Additional and Conceptual Content AdditionalContent В дополнительно открывшемся окне добавьте при помощи кнопки «File» наши страницы Index.htm и Details.htm. Дополнительные статические HTML страницы. Build ComponentConfigurations Выберите в открывшемся окне Code Block Component. Мы его используем для подсветки синтаксиса из статической страницы. FrameworkVersion 2.0.50727 Укажите здесь используемую в приложении версию .Net HelpFileFormat Help1xAnd2xAndWebsite Выберите один или несколько выходных форматов: HtmlHelp1x/HtmlHelp2x/WebSite. Help File HelpTitle Тестовое консольное приложение Наш заголовок HtmlHelpName HelloWorldApplication Имя выходного файла справки PresentationStyle vs2005 Тут уж на ваше предпочтение, мне привычней «vs2005» вместо «hana» или «Prototype» RootNamespaceContainer True Мы отделим наше описание классов в отдельный узел справки RootNamespaceTitle Namespaces и дадим ему наше имя Paths HtmlHelp1xCompilerPath C:\Program Files\HTML Help Workshop\ Путь к HTML Help Workshop and Documentation HtmlHelp2xCompilerPath C:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\ Путь к «Microsoft Help SDK», который устанавливается с Visual Studio SDK (2003/2005/2008), например, Visual Studio 2008 SDK 1.1 OutputPath .\HelpResult\ Путь, куда будет скопирована готовая документация SandcastlePath C:\Program Files\Sandcastle\ Путь к Sandcastle, скорректируйте его в соответствии с вашими установками WorkingPath .\SandcastleWorkingFolder\ Путь к рабочей папке, где будут складываться промежуточные результаты работы
- Сохраним проект для повторного использования.
- Строим документацию.
Результаты работы
1. Microsoft Compiled HTML Help (CHM)
Справка в виде CHM
Справка в виде CHM — статическая страница
2. MS Microsoft Help 2
Интегрированная справка в формате MSDN
3. Статический веб-сайт
Справка в виде обычных HTML страниц
4. Динамический веб-сайт (ASP.NET)
Справка в виде динамического сайта с поиском
Дополнительная информация
Все используемые выше коды, проект Help File Builder и результаты его работы вы можете найти в архиве SandcastleTestProject.zip на narod.yandex.ru или drop.io (391KB).
Ссылки для дальнейшего изучения:Я показал только базовые возможности Sandcastle. Надеюсь, что вам было интересно и если вы еще не использовали его, то теперь попробуете. Спасибо за внимание.