Настройка разделов документации SHFB

Чтобы удалить разделы «Inheritance Hierarchy», «Syntax» и «See Also» в Sandcastle Help File Builder (SHFB), необходимо настроить параметры стиля представления и свойства проекта для настройки формата вывода, либо использовать компоненты сборки для фильтрации нежелательных разделов во время генерации документации.

Contents

• Understanding SHFB Output Customization
• Method 1: Using Presentation Style Settings
• Method 2: Modifying Project Properties
• Method 3: Custom Build Components
• Method 4: Token Replacement for Content Filtering
• Creating User-Style Documentation
• Best Practices for Documentation Customization

Understanding SHFB Output Customization

Sandcastle Help File Builder (SHFB) предоставляет обширные возможности настройки через свойства проекта и компоненты сборки. При генерации документации SHFB создаёт техническую API‑документацию, в которой по умолчанию присутствуют разделы, такие как Inheritance Hierarchy, Syntax и See Also. Для пользовательской документации, ориентированной на практическое использование, эти разделы часто нужно удалить или изменить.

Согласно официальной документации EWSoftware по SHFB, «Sandcastle Help File Builder standalone GUI предоставляет среду, в которой можно редактировать свойства, контролирующие функции и внешний вид скомпилированного файла справки». Это позволяет адаптировать вывод под разные аудитории – от технических разработчиков до конечных пользователей.

Method 1: Using Presentation Style Settings

Самый простой способ удалить нежелательные разделы – настроить параметры стиля представления в проекте SHFB.

Шаги по изменению стиля представления:

1. Откройте проект SHFB в standalone GUI или интеграции Visual Studio.
2. Перейдите в окно свойств проекта.
3. Найдите раздел Presentation Style в сетке свойств.
4. Выберите подходящий стиль для пользовательской документации, например:
   • VS2013 (для современного вида)
   • Prototype (для минимального технического контента)
   • ManagedReference (для базового форматирования)

Разные стили представления имеют различное поведение по умолчанию относительно включения разделов. Официальная документация SHFB объясняет, что «шаблоны файлов справки, а также различные файлы в вашем собственном проекте, такие как файлы токенов, могут содержать один или несколько из следующих тегов замены», которые управляют включением контента.

Конфигурация стиля представления:

Method 2: Modifying Project Properties

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

Ключевые свойства для изменения:

1. Namespace Summaries – установить в true, если нужна документация уровня пространства имён.
2. Include Inherited Members – установить в false, чтобы убрать списки унаследованных членов.
3. Show Missing Tags – установить в false, чтобы не отображать предупреждения о недостающей документации.
4. Source File Comments – настроить включение или исключение комментариев уровня файла.

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

Расширенная конфигурация свойств:

В файле проекта можно изменить раздел buildAssemblerProperties, добавив:

<property name="IncludeInheritanceHierarchy" value="false"/>
<property name="IncludeSyntax" value="false"/>
<property name="IncludeSeeAlso" value="false"/>

Эта XML‑конфигурация напрямую нацелена на удаление нужных разделов из вывода документации.

Method 3: Custom Build Components

Для более продвинутой настройки SHFB позволяет создавать или модифицировать компоненты сборки, которые обрабатывают документацию во время процесса сборки.

Создание пользовательских компонентов:

1. Создайте новый компонент сборки, наследующийся от соответствующего базового класса.
2. Переопределите метод Process для фильтрации нежелательных разделов.
3. Добавьте компонент в процесс сборки вашего проекта SHFB.

В репозитории GitHub SHFB приведены примеры и шаблоны для создания пользовательских компонентов, которые могут манипулировать структурой документации. Как описано в репозитории, SHFB предоставляет «полную конфигурацию и расширяемость для сборки файлов справки с помощью инструментов Sandcastle».

Пример реализации компонента:

public class SectionFilterComponent : BuildComponent
{
    public override void BuildComponent(BuildEventArgs e)
    {
        // Фильтруем разделы Inheritance Hierarchy, Syntax и See Also
        // Реализация зависит от конкретного типа компонента сборки
    }
}

Method 4: Token Replacement for Content Filtering

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

Конфигурация файла токенов:

1. Создайте файл токенов в проекте SHFB.
2. Определите токены, контролирующие включение разделов:
   • {csdn:IncludeInheritanceHierarchy} – установить в false, чтобы удалить раздел Inheritance Hierarchy.
   • {csdn:IncludeSyntax} – установить в false, чтобы удалить раздел Syntax.
   • {csdn:IncludeSeeAlso} – установить в false, чтобы удалить раздел See Also.

Официальная документация SHFB о настройке процесса сборки объясняет, что «эти теги будут заменены соответствующим значением проекта, чтобы получить файл справки».

Пример файла токенов:

# Удаляем технические разделы для пользовательской документации
{csdn:IncludeInheritanceHierarchy}=false
{csdn:IncludeSyntax}=false
{csdn:IncludeSeeAlso}=false
{csdn:IncludeRemarks}=true  # Сохраняем дружелюбные примечания
{csdn:IncludeExamples}=true # Сохраняем практические примеры

Creating User-Style Documentation

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

Области фокуса контента:

1. Примеры и сценарии использования – добавьте практические фрагменты кода, показывающие, как использовать функции.
2. Пошаговые инструкции – включите руководства по выполнению типичных задач.
3. Концептуальный обзор – предоставьте высокоуровневые объяснения вместо технических деталей.
4. Руководства по устранению неполадок – помогите пользователям решать распространённые проблемы.

Рекомендации по структуре документации:

- Введение (Что это за функция?)
- Начало работы (быстрый старт)
- Распространённые задачи (Как сделать X, Y, Z)
- Примеры (фрагменты кода и объяснения)
- FAQ (часто задаваемые вопросы)

Как отмечено в статье Simple Talk о Sandcastle, эффективная документация требует понимания аудитории и соответствующей структуры контента.

Best Practices for Documentation Customization

Тестирование и проверка:

1. Постоянно собирайте и проверяйте документацию во время настройки.
2. Проверьте вывод в разных форматах справки (HTML, CHM и т.д.).
3. Получайте обратную связь от целевой аудитории.
4. Контролируйте версии ваших конфигураций документации.

Уход за поддержкой:

1. Документируйте свои настройки для будущего использования.
2. Обновляйте конфигурации при переходе на новые версии SHFB.
3. Создавайте шаблоны для разных типов документации.
4. Автоматизируйте сборки для обеспечения консистентности.

Дополнительные рекомендации можно найти в FAQ SHFB, где рассматриваются распространённые проблемы и решения.

Conclusion

Создание пользовательской документации с SHFB требует удаления технических разделов, таких как «Inheritance Hierarchy», «Syntax» и «See Also». Это можно сделать через:

1. Настройку стиля представления – выбор стилей, минимизирующих технический контент.
2. Изменение свойств проекта – точная настройка включения разделов.
3. Создание пользовательских компонентов сборки – продвинутая фильтрация.
4. Замена токенов – гибкая настройка контента во время сборки.

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

Sources

1. Stack Overflow – How to remove ‘Inheritance Hierarchy’, ‘Syntax’, and ‘See Also’ sections in SHFB?
2. EWSoftware SHFB Documentation – Customizing the Build Process
3. EWSoftware SHFB Documentation – Sandcastle Help File Builder Overview
4. GitHub – EWSoftware/SHFB: Sandcastle Help File Builder
5. Simple Talk – Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code
6. SHFB FAQ – Frequently Asked Questions
7. CodeProject – Sandcastle Help File Builder