Создание help файла visual studio

Обновлено: 05.07.2024

Разработчик имеет в своем распоряжении широкий спектр технологий. Они не только очень быстро развиваются, но и вынуждают программистов постоянно овладевать новыми знаниями. Поскольку все обо всем знать невозможно, разработчик должен непрерывно учиться. Часто знание того, как найти информацию о той или иной технологии, является таким же важным, как и способность ее освоить. К счастью, существует множество информационных источников, содержащих информацию об этих технологиях. Включение в интегрированные среды разработки технологии автоматического дополнения IntelliSense, произошедшее около десяти лет назад, стало одним из важнейших обстоятельств, облегчивших работу разработчиков, но этот инструмент не может полностью заменить полноценную справочную систему, содержащую подробную информацию. Чтобы решить эту задачу, в среду Visual Studio включена справочная система для разработчиков.

Проще всего получить справку в среде Visual Studio 2013, использовав тот же метод, что и в любом другом Windows-приложении - нажав универсальную клавишу <F1> . Среда Visual Studio 2013 имеет свою фирменную справочную систему, использующую технологию Microsoft Help 3. Вместо использования специальной "оболочки" и предоставления пользователю средств навигации по ней справочная система теперь открывает окно браузера. Для доступа к более сложным возможностям справочной системы, например возможностям поиска (при работе в автономном режиме), существует специальное приложение "слушатель" (listener), выполняющееся в области системных уведомлений и обслуживающее запросы пользователей. Как в интерактивном, так и в автономном режиме справочная система и выглядит, и работает почти одинаково.

Справочная система в среде Visual Studio является контекстно-зависимой. Это означает, что если курсор в настоящий момент расположен в определении класса в проекте и пользователь нажал клавишу <F1> , то в окне справки моментально откроется мини-учебник о текущей инструкции и способах ее использования:

Это невероятно полезное свойство, поскольку в этом случае вы быстрее получите необходимую информацию, чем если просто нажмете клавишу <F1> и станете искать нужное описание, листая справочную систему. Однако в некоторых ситуациях следует перейти сразу к содержанию справочной системы. Среда Visual Studio 2013 позволяет сделать это с помощью команды View Help меню Help.

Кроме использования справочной системы, пользователь также может зайти на форумы MSDN и сообщить о проблеме.

Навигация и поиск в справочной системе

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

В правом верхнем углу окна браузера имеется окно для ввода поискового запроса, который вводится точно так же, как и в любой поисковой системе, например Google или Bing. Поиск является полнотекстовым и распространяется на все страницы справочной системы, причем запрос не обязательно должен содержаться в заголовках страниц. В итоге пользователь получит результаты, аналогичные результатам, которые он мог бы получить с помощью любой поисковой машины. В окне выводится по одной строке о каждом результате, чтобы можно было найти требуемый. Чтобы прочитать нужную статью, следует щелкнуть на соответствующей строке.

Конфигурирование справочной системы

Когда пользователь впервые обращается к справочной системе, целесообразно настроить ее под свои нужды. Для этого можно выбрать команду Help --> Set Help Preferences. Всплывающее меню предлагает два варианта: интерактивный (Use Online Help) или автономный режим работы (Launch in Helper Viewer). Если пользователь выбирает интерактивный режим, то нажатие клавиши <F1> или открытие справки из меню Help автоматически приведет его на соответствующую страницу в документации MSDN, расположенной в Интернете (с учетом текущего контекста системы Visual Studio). Выбирая автономный режим, пользователь попадет на соответствующую страницу в документации, установленной локально (при условии, что она действительно была развернута на данном компьютере).

Преимущество интерактивного режима над автономным заключается в том, что он всегда предоставляет обновленную информацию и не требует затрат памяти на жестком диске пользователя (при условии, что он не разворачивал справочную систему локально). Недостатком является необходимость постоянно поддерживать активное соединение с Интернетом и временами более медленная работа (в зависимости от ширины полосы пропускания), чем в автономном режиме. По существу, это компромисс, на который пользователь должен пойти самостоятельно.

Итак, новая справочная система представляет собой мощный интерфейс, обеспечивающий доступ к документации, сопровождающей пакет инсталляции Visual Studio 2013. Возможность переключаться между автономным и интерактивным режимами позволяет устанавливать баланс между скоростью поиска информации в локальной документации и релевантностью информации, найденной в веб. Кроме того, для каждого результата поиска она показывает один абзац, независимо от его расположения, чтобы минимизировать количество ложно позитивных результатов.

Файл указаний содержит макрос, который в противном случае вызвал бы пропуск областей кода средством синтаксического анализа базы данных просмотра C++. При открытии проекта Visual Studio C++ система синтаксического анализа анализирует код в каждом исходном файле проекта и создает базу данных с информацией обо всех идентификаторах. Затем интегрированная среда разработки использует эту информацию для поддержки таких функций просмотра кода как обозреватель представления классов и панель навигации.

Средство синтаксического анализа базы данных просмотра C++ — это средство нечеткого синтаксического анализа, которое может анализировать большие объемы кода за короткий промежуток времени. Высокая скорость его работы объясняется в том числе и тем, что оно пропускает содержимое блоков. Например, оно записывает только расположение и параметры функции и игнорирует ее содержимое. Определенные макросы могут вызвать проблемы для эвристических правил, используемых для определения начала и конца блока. Эти проблемы приводят к тому, что области кода записываются неправильно.

Пропущенные области кода могут проявляться несколькими способами:

Отсутствуют типы и функции в представлении классов, в окне Перейти к и на панели навигации

Неправильные области на панели навигации

Предложения по Созданию объявления или определения функций, которые уже определены

Файл указаний содержит настраиваемые пользователем указания, которые имеют тот же синтаксис, что и определения макросов C/C++. В Visual C++ есть внутренний файл указаний, которого достаточно для большинства проектов. Однако вы можете создавать собственные файлы указаний, чтобы улучшить работу средства синтаксического анализа специально для вашего проекта.

При изменении или добавлении файла указаний необходимо выполнить дополнительные действия для того, чтобы изменения вступили в силу:

в версиях до Visual Studio 2017 версии 15,6: удалите sdf-файл и (или) файл VC. db в решении для всех изменений.
в Visual Studio 2017 версии 15,6 и более поздних: закройте и снова откройте решение после добавления новых файлов подсказок.

Сценарий

Без файла указаний Function не отображается в представлении классов, в окне Перейти к и на панели навигации. После добавления файла указаний с этим определением макроса средство синтаксического анализа может распознать и заменить макрос NOEXCEPT , что позволяет ему корректно проанализировать функцию:

Макросы, нарушающие работу

Существует две категории макросов, нарушающие работу средства синтаксического анализа:

Макросы, которые инкапсулируют ключевые слова, декорирующие функцию

Для следующих типов макросов в файле указаний необходимо указать только имя макроса:

Макросы, которые содержат несбалансированные скобки

Для следующих типов макросов в файле указаний необходимо указать имя макроса и его содержимое:

Поддержка редактора

Начиная с Visual Studio 2017 версии 15.8 существуют несколько функций, которые позволяют определить макросы, нарушающие работу средства синтаксического анализа:

Макросы, которые находятся внутри областей, пропущенных анализатором, выделяются.

Существует быстрое действие для создания файла указаний, включающего выделенный макрос, или (при наличии существующего файла указаний) для добавления макроса в файл указаний.

После выполнения любого из быстрых действий средство анализа повторно анализирует файлы, на которые повлиял файл указаний.

По умолчанию проблемный макрос выделяется как предложение. Выделение можно изменить на более заметное, например, подчеркивание красной или зеленой волнистой линией. Используйте параметр Макросы в пропущенных областях просмотра в разделе Подчеркивание кода, который можно открыть, выбрав Инструменты > Параметры > Текстовый редактор > C/C++ > Представление.

Отображение ошибок базы данных просмотра

команда меню Project > отображения ошибок базы данных обзора отображает все регионы, которые не удалось проанализировать в список ошибок. Команда призвана упростить создание начального файла указаний. Тем не менее, средство синтаксического анализа не может определить, был ли причиной ошибки макрос, нарушающий работу средства синтаксического анализа, поэтому вам необходимо оценить каждую ошибку самостоятельно. Выполните команду Показать ошибки базы данных просмотра и перейдите к каждой ошибке, чтобы загрузить соответствующий файл в редакторе. После загрузки файла все макросы, входящие в область, будут выделены. Вы можете вызвать быстрые действия, чтобы добавить их в файл указаний. После обновления файла указаний список ошибок обновляется автоматически. Кроме того, если вы изменяете файл указаний вручную, можно использовать команду Повторить сканирование решения, чтобы запустить обновление.

Architecture

Файлы указаний относятся к физическим каталогам, а не к логическим каталогам, отображаемым в обозревателе решений. Чтобы файл указаний был применен, добавлять его в проект не нужно. Система анализа использует файлы указаний только при анализе исходных файлов.

Каждый файл указаний называется cpp.hint. Файлы указаний могут размещаться в различных каталогах, но в отдельном каталоге может находиться лишь один такой файл.

В проекте может использоваться как один или несколько файлов указаний, так и ни одного. При отсутствии файлов указаний система анализа использует методики восстановления после ошибок, чтобы пропускать нераспознаваемый исходный код. В противном случае система анализа использует указанную ниже стратегию для обнаружения и сбора указаний.

Порядок поиска

Система анализа ищет файлы указаний в каталогах в следующем порядке.

Каталог, содержащий пакет установки для Visual C++ (vcpackages). Этот каталог содержит встроенный файл указаний, описывающий символы в часто используемых системных файлах, таких как windows.h. Поэтому проект автоматически наследует основную часть нужных ему указаний.

Путь из корневого каталога исходного файла к каталогу, содержащему сам исходный файл. В типичном проекте Visual Studio C++ корневой каталог содержит файл проекта или решения.

Исключением из этого правила является ситуация, когда стоп-файл находится в пути к исходному файлу. Стоп-файл — это любой файл с именем cpp.stop. Стоп-файл обеспечивает дополнительный уровень контроля над порядком поиска. Вместо того чтобы начать с корневого каталога, система анализа выполняет поиск из каталога, содержащего стоп-файл, по направлению к каталогу, содержащему исходный файл. В обычных проектах стоп-файлы не требуются.

Сбор указаний

Система анализа открывает каждый файл указаний в указанном выше порядке поиска. Она собирает указания из каждого файла в набор полезных указаний, а затем использует эти полезные указания для интерпретации идентификаторов в коде.

Система анализа использует эти правила для сбора указаний:

Если новое указание задает имя, которое еще не было определено, новое указание добавляет имя в список полезных указаний.

Если новое указание задает уже определенное имя, существующее имя переопределяется.

Первое правило означает, что полезные указания наследуются от ранее открытых файлов указаний. Два последних правила означают, что более поздние указания в порядке поиска могут переопределять более ранние. Например, можно переопределить любые имеющиеся указания, создав файл указаний в каталоге с исходным файлом.

Описание сбора указаний см. в разделе Пример ниже.

Синтаксис

В указаниях используется следующий синтаксис:

Пример

В этом примере показано, как выполняется сбор указаний из соответствующих файлов. Стоп-файлы в этом примере не используются.

На рисунке показаны некоторые физические каталоги в проекте Visual Studio C++. Файлы указаний находятся в каталогах vcpackages , Debug , A1 и A2 .

Каталоги файлов указаний

Каталоги и содержимое файлов указаний

В списке ниже приведены каталоги в этом проекте, содержащие файлы указаний, и содержимое этих файлов. Приведены лишь некоторые из указаний в файле указаний каталога vcpackages :

Полезные указания

В следующей таблице приведены полезные указания для исходных файлов в этом проекте:

Исходный файл: A1_A2_B.cpp

Эти замечания применяются к предыдущему списку:

Эти полезные указания получены из каталогов vcpackages , Debug , A1 и A2 .

Файл указаний в каталоге A1 переопределяет START_NAMESPACE .

На этом шаге мы рассмотрим создание справки HTML Help .

Справочная система HTML Help предлагается фирмой Microsoft в качестве платформы для справочных систем следующего поколения. Для отображения справки в ней применяются разнообразные компоненты Microsoft Internet Explorer : языки HTML и Java , элементы управления на базе ActiveX , сценарии JavaScript и Microsoft Visual Basic Scripting Edition , графические файлы в форматах JPEG и GIF . Все эти элементы позволяют создать справочную систему, обладающую можностями и внешним видом полноценного Web -узла. Эту систему можно снабдить ссылками на внешние ресурсы, чтобы, например, при необходимости обращаться к Web -узлу.

Средство просмотра HTML -справки содержит панель инструментов и элементы управления для оглавления и предметного указателя, предназначенные для перемещения по страницам справки.

Установка HTML Help .
1. Запустите программу Htmlhelp.exe , которая находится в каталоге HtmlHelp на диске 1 дистрибутива Visual C++ или Visual Studio.
2. Следуя инструкциям, установите HTML Help в папку по умолчанию C:\Program Files\HTML Help Workshop .
Преобразование проекта WinHelp .
1. В Visual Studio закройте все открытые проекты. Открыв в Проводнике папку проекта МуАрр , создайте в ней подкаталог hlp .
2. В меню Пуск выберите подменю Программы , затем - HTML Help Workshop и, наконец, HTML Help Workshop .
3. В HTML Help Workshop в меню File щелкните New .
4. Выберите создание нового проекта, щелкнув ОК .

Рис.1. Выбор нового проекта

Рис.2. Установка флажка Convert WinHelp Project

Рис.3. Второй шаг мастера

Рис.4. HTML Help Workshop

Вызов HTML -справки из приложения МуАрр .
В Visual C++ откройте проект МуАрр . В меню Project выберите команду Settings .
Щёлкните вкладку Link . В списке Category выберите Input .
В поле Object/library modules modules введите htmlhelp.lib .
В поле Additional library path задайте путь к каталогу, где находится файл htmlhelp.lib (например C:\Program Files\HTML Help Workshop\lib ).

Рис.6. Окно Project Settings , вкладка Link

Рис.7. Окно Project Settings , вкладка C/C++

Рис.8. Пункт меню &Help Topics

Рис.9. Создание функции OnHelpHelptopics()

В Вашей программе этот кодможет выглядеть иначе, если путь к СНМ -файлу отличается от выбранного нами. Заметьте, что в текстовых строках символ \ должен быть представлен ESC -последовательностью \\ . Разбивая текстовую строку на несколько строк, не забудьте вставлять в конце каждой строки символ продолжения \ .

Есть разные подходы к написанию документации. Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто-то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки.

Я в своей работе использовал и сторонние средства, и встроенные. Начинал писать документацию и сразу, и в последний момент. В итоге я для себя решил, что документацию лучше начинать писать во второй половине создания продукта, так как чем ближе к завершению, тем более стабилен API, набор возможностей и т.п., а значит, реже придется корректировать документацию. Написание документации прямо в коде тоже, в конечном счете, оказалось удобнее, чем в сторонних программах, хотя поначалу казалось совсем наоборот. Эта статья как раз о том, как писать документацию прямо в коде.

Описываем API

/// <summary>
/// Gets the R component from ABGR value returned by
/// <see cref="O:BitMiracle.LibTiff.Classic.Tiff.ReadRGBAImage">ReadRGBAImage</see>.
/// </summary>
/// <param name="abgr">The ABGR value.</param>
/// <returns>The R component from ABGR value.</returns>
public static int GetR ( int abgr )
<
return ( abgr & 0xff ) ;
>

По умолчанию создание xml-файла из комментариев отключено. Его нужно включить в свойствах проекта на вкладке Build.

В результате при компиляции, в дополнение к файлу вашей сборки, будет сгенерирован xml-файл, который содержит все xml-комментарии из кода (в том числе комментарии к непубличным структурам). Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции IntelliSense в Visual Studio отображать описания для методов в момент набора пользователем кода. Вот пример того, как это будет выглядеть для функции GetR, показанной выше:

Однако в большинстве случаев сгенерированный xml-файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml-файл так, чтобы в нем остались только описания к публичным методам.

Я не буду подробно рассматривать все xml-теги, а лишь попробую кратко описать наиболее часто используемые.

Тег summary служит для краткого описания назначения класса, интерфейса, перечисления (enum), методов и свойств класса или интерфейса и членов перечисления. Тег param позволяет описать параметр, принимаемый функцией. Этот тег нужно использовать для каждого принимаемого параметра. Тег returns используется для описания возвращаемого значения функции. Тег value полезен для описания значения, которое принимает и/или возвращает некоторое свойство. В некотором смысле тег value является аналогом тега returns.

/// <summary>
/// Gets the font ascent.
/// </summary>
/// <value>The font ascent.</value>
/// <remarks>Ascent is the maximum height above the baseline reached
/// by glyphs in this font, excluding the height of glyphs for
/// accented characters.</remarks>
public short Ascent
<
get
<
return Impl. Ascent ;
>
>

Очень полезным (и, к сожалению, часто игнорируемым) является тег remarks, который позволяет указать примечания к описываемой сущности. Этот тег можно использовать практически везде кроме описания членов перечисления. На самом деле для членов перечисления тоже можно, но в документации, оформленной в стиле vs2005, этих примечаний просто не будет видно, что уменьшает полезность таких примечаний.

Приведу еще несколько практических замечаний/рекомендаций.

Скачайте и установите расширение для Visual Studio под названием GhostDoc. Это расширение работает во всех версия студии (начиная с версии 2005) и сильно упрощает создание xml комментариев. По нажатию на Ctrl-Shift-D это расширение вставляет описание сущности, на которой в данный момент стоит курсор. Вставляются все необходимые теги, и генерируется текст описания на основе, например, названия метода и названия его параметров. Часто остается лишь откорректировать и дополнить сгенерированный текст.

Недостаток написания документации прямо в коде в том, что комментариев порой больше, чем кода, что может сильно затруднять чтение кода. Для обхода этой проблемы очень удобным оказывается полное разделение публичного интерфейса и реализации.

Если у вас есть несколько перегруженных методов, то при генерации документации для них будет создана отдельная страница (вот пример такой страницы). Текст для этой страницы нужно указать в теге overloads в описании одного из перегруженных методов.

/// <summary>
/// Saves the font bytes to the specified stream.
/// </summary>
/// <param name="stream">The stream to save font bytes to.</param>
/// <overloads>Saves the font bytes to a file or a stream.</overloads>
public void Save ( Stream stream )
<
Impl. Save ( stream ) ;
>

Если вы хотите в описании одного метода дать ссылку на другой метод или тип, то нужно использовать конструкцию вида <see cref="X:MEMBER">Текст ссылки</see> , где X – необязательный префикс, обозначающий тип сущности (T для класса, M для метода, P для свойства, O для группы перегруженных методов), а MEMBER – полная или частичная спецификация сущности. Частичную спецификацию и отсутствующий префикс можно использовать, например, для ссылок между двумя методами одного класса или между двумя сущностями одного пространства имен (namespace).

Пример использования частичной спецификации (PdfFontEmbedStyle находится в одном пространстве имен с PdfFont):

public sealed class PdfFont
<
…
/// <summary>
/// Gets or sets the <see cref="PdfFontEmbedStyle"/> value that specifies
/// how this font is embedded into the document.
/// </summary>
/// <value>The <see cref="PdfFontEmbedStyle"/> value that specifies
/// how this font is embedded into the document.</value>
public PdfFontEmbedStyle EmbedStyle
<
get
<
return Impl. EmbedStyle ;
>
set
<
Impl. EmbedStyle = value ;
>
>
>

ссылка на свойство
<see cref="P:System.Exception.HResult"/>
ссылка на метод
<see cref="M:BitMiracle.LibTiff.Classic.Tiff.GetR(System.Int32)"/>
ссылка на группу перегруженных методов
<see cref="O:BitMiracle.LibTiff.Classic.Tiff.PrintDirectory"/>
ссылка на класс
<see cref="T:BitMiracle.LibTiff.Classic.TiffTagMethods"/>

Со ссылками на группу перегруженных методов связана одна неприятность. Visual Studio требует, чтобы такие ссылки были вида O:XXX.YYY , в то время как Sandcastle Help File Builder требует, чтобы такие ссылки были вида Overload:XXX.YYY . Для решения этой проблемы я использую простой скрипт, который вызывается на Post-build event и заменяет в xml-файле O: на Overload: , что вполне терпимо.

Для ссылки на некоторую внешнюю статью вашей документации (не связанную с описанием API) или на некоторый ресурс в Интернет используйте старый добрый тег <a> с атрибутом href. Например, <a href = "54cbd23d-dc55-44b9-921f-3a06efc2f6ce.htm">Текст ссылки</a> или <a href = "http://site.com/page.html">Текст ссылки</a> . В первом примере имя документа с внешней статьей представлено в форме “TOPIC_ID.htm”. О том, что такое topic id, речь пойдет далее.

Генерируем файл документации

секция Build: FrameworkVersion
секции Help File: CopyrightHref, CopyrightText, FeedbackEMailAddress, FeedbackEMailLinkText, HelpTitle, HtmlHelpName
секция Paths: OutputPath

Еще один важный шаг – описать пространства имен (namespace-ы) в SHFB. Xml комментарии в коде не работают для namespace-ов, поэтому нужно это сделать вручную. Тут поможет секция Comments и свойство NamespaceSummaries в ней. В описании namespace-ов можно использовать стандартные html теги.

Настройка проекта завершена, пришло время построить сhm-файл. Выбираем Documentation->Build Project, и, если все было сделано правильно, то получаем красивый файл документации в стиле MSDN.

Пишем статьи

Однако не стоит останавливаться на достигнутом – одного описания API вашего компонента не достаточно для полноценной документации. Хорошая документация обычно содержит дополнительные статьи, примеры, FAQ и т.п.

В окне Project Explorer добавляем новый элемент Content Layout – это описание (с указанием взаиморасположения) того, что входит в документацию. В окне Content Layout добавляются новые статьи (topics). Каждая статья описывается в MAML формате (.aml файлы), это xml-based формат. Sandcastle Help File Builder поставляется с набором предопределенных шаблонов, что значительно упрощает дебют в написании статей. Я в основном использую шаблон Conceptual, реже – Walkthrough.

Описание каждой статьи начинается с указания topic id – уникального идентификатора. На основе этого идентификатора генерируется html файл, который позже попадет в chm. Генерируемый html-файл именуется в форме “TOPIC_ID.htm”. Данный topic id используется также для ссылок на статью из других статей или xml-комментариев в коде.

При создании статьи предлагается ее сохранить в файл с именем “TOPIC_ID.aml”. Можно и нужно при создании сразу указать нормальное имя для файла.

Рассмотрим некоторые элементы управления в SHFB, которые полезны при редактировании статей.

	Устанавливает стартовую страницу документации (будет показываться при открытии документации.
	Устанавливает положение, в которое будет вставлено описание API, сгенерированное из xml-файла. В зависимости от того, какой вариант выбран, описание API будет вставлено либо перед, либо после, либо как дочерний элемент помеченного таким образом элемента.
	Предварительный просмотр текущей статьи.
	Вставка ссылки на статью в документации. Используйте topic id в качестве адреса.
	Вставка стандартных тегов для разметки статьи.

Окно Entity Reference (на картинке расположено справа) можно использовать для вставки ссылок на описание функций/методов и т.п. сущностей из кода. Такой способ вставки ссылок не очень удобен на мой взгляд, так как нужно сначала открыть текст статьи, потом открыть окно Entity Reference, потом в этом окне написать часть или полное названия сущности, потом найти в списке нужную строку и дважды кликнуть на нее. Все это приведет к тому, что в статью вставится ссылка в позиции курсора. Я предпочитаю писать ссылки руками, а текст для ссылок находить в build log-е (лог от предыдущего билда можно открыть в текстовом редакторе).

Для вставки кода в статью используется тег <code> . Например:

< code language = "cs" >
private void helloWorld ( )
<
Console. WriteLine ( ”Hello World ! ” ) ;
>
</ code >

В окне Project Explorer выбираем Add, потом Existing Item и выбираем нужную картинку.
В свойствах добавленного файла меняем BuildAction на Image, а свойство ImageId – на удобное название (будет использоваться в ссылках на это изображение).

<mediaLink><image xlink: href = "ImageId" placement = "center" / >< / mediaLink>

К сожалению, в текущей версии SHFB редактор далек от совершенства. Например, теги не закрываются автоматически, очень много действий приходится делать мышью (нет хоткеев), не для всех стандартных тегов есть соответствующие элементы на тулбаре. Парадоксально, но мне для большинства действий с aml-файлами удобнее использовать Visual Studio. Разумеется, можно использовать и любой другой удобный xml-редактор для написания статей.

Интеграция в процесс сборки

Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект. То есть вы не сможете увидеть содержимое такого проекта, проект лишь добавится в группу Solution Items.

Для solution выбираете Add->Existing Item…, добавляете проект документации. Будет добавлен в папку Solution Items.
Щелкаете по добавленному элементу правой кнопкой мыши и выбираете Open With… В открывшемся диалоге добавляете ”Sandcastle Help File Builder GUI” и устанавливаете его в качестве редактора по умолчанию.

Более полезна сборка документации из командной строки. Такую сборку можно делать на Post-Build event или в других случаях. Собрать документацию из командной строки очень просто следующей командой:
%SystemRoot%\Microsoft.NET\Framework\v3.5\MSBuild.exe" /p:Configuration=Release Help.shfbproj
В этой строке Help.shfbproj – название проекта документации.

Надеюсь, эта статья поможет вам начать писать документацию к вашим проектам (если вы еще этого не делаете) за что ваши пользователи наверняка скажут вам спасибо. Успехов вам в написании документации!

Читайте также: