How To Use the Topic Management Dialog
The Topic Management Dialog aggregates three tool windows that are available in Visual Studio Standard and higher: Topic Explorer
, Topic Filters
and Topic Editor
. The dialog is available as a project option in Visual Studio and the DocProject External UI
provides a tree view for creating the table of contents (TOC), creating and managing conceptual documentation and choosing the topics that will be built by Sandcastle.Topic Filters
provides the ability to include or exclude topics using regular expressions, categorical filters and even custom filters.Topic Editor
provides the ability to create external
XML documentation for the project, namespaces and API elements in source mode and design mode.
Finding the Dialog
The dialog can be accessed by clicking a button on the Sandcastle toolbar (Figure 1
) when using the DocProject External UI
. In Visual Studio Standard or higher this button will open Topic Explorer
instead, from which the other tool windows can be opened.
To open the Topic Filters
window from Topic Explorer
, click the toolbar button with a filter icon
To open the Topic Editor
window from Topic Explorer
, double-click an auto-generated reference topic or right-mouse click and select Edit
. Note that conceptual topics will open in Visual Studio's built-in XML editor instead.Figure 1:
Finding Topic Explorer and the Topic Management Dialog - Sandcastle Toolbar
The dialog can also be opened in the DocProject Properties
window and the DocProject External UI
) by clicking the ellipses button of the Content
> Topic Management
Finding the Topic Management Dialog - DocProject Properties
The MRefBuilder Configuration File Name
property in the Active Projects
page specifies the name of the configuration file, located in the Help\Presentation\Style\Configuration
directory, that is to be managed by the dialog and used with the Sandcastle MRefBuilder
Where are my topics?
The source assemblies have to be present in order for Topic Explorer to display their topics. It does not automatically build all of the source projects so you must build the projects before using it. If you build a source project and then close and reopen Visual Studio the assembly will still exist, so you won't need to build the project again to use Topic Explorer for that source project.
If you only build some of the source projects then Topic Explorer will only display the API topics for the assemblies that you have built. If you clean the solution or otherwise delete any of the output assemblies from the source projects then the corresponding API topics will not be displayed.
Topic Explorer displays the table of contents (TOC) as it will be built by DocProject. The tool bar and a context menu provide various functions for working with topics and accessing other tool windows.Figure 3:
Topic Explorer toolbarFigure 4:
Topic Management dialog toolbar
You can use the Topic Explorer tool bar (Figure 3
and Figure 4
) to insert and import conceptual topics and raw HTML topics. Once added, you can drag & drop topics to create the table of contents (TOC).
Conceptual documentation is built when at least one conceptual topic is added. If auto-generated reference documentation is also built, DocProject will merge them together automatically to create a single documentation set.
Conceptual topics must be written in the XML-based Microsoft Assistance Markup Language
(MAML). The files are stored in the project's Help\Topics
folder with an .aml
extension and a friendly file name, which is not used for any purpose other than making it easier to find coneptual topic files on disc. Each conceptual topic also has an XML companion file, with a .cmp
extension, that stores metadata for the topic. Metadata includes the TOC title and the display title, Help 2.x attributes like DocSet
, as well as index keywords.Note:
Visual Basic projects do not show dependent files by default. To see the companion files you must use the Show All Files
command in Solution Explorer.
You can manage a conceptual topic's metadata by manually editing its companion file using Visual Studio's XML editor or you can use the Topic Properties
window by right-mouse clicking the topic in Topic Explorer
and selecting Properties
. Changes are committed when the Save All
command is executed in Visual Studio or when the Save
command is executed in the DocProject External UI.
For more information about Sandcastle's support for conceptual documentation using MAML, see Sandcastle Help, MAML
.Important: Renaming Topic Files
Renaming conceptual topic files is not currently supported so it's recommended that you choose appropriate file names when topics are created.
However, if you need to change a toipc's file name then follow these steps:
- Change the file name of the conceptual topic in the Help\Topics folder.
- Update the name of its XML companion file so that it has the same base file name as the topic, but with a .cmp extension.
- Note: Visual Studio may not let you do this in Solution Explorer. The only alternative is to unload the project file, edit it manually and then reload the project.
- Update the Help\Settings\topics.xml file to use the new topic name.
attribute on topic
elements in the topics.xml
file supports a relative path from the Help\Topics
folder, so you can move conceptual topic files into subfolders of Help\Topics
but you must update the path in the topics.xml
file manually. Then click the Refresh
toolbar button in Topic Explorer
to load the updated topics.xml
Auto-Generated Reference Topics
Reference topics that will be automatically generated by Sandcastle for project references
and external sources
appear under the root Namespaces
topic in Topic Explorer if at least one source is configured. The root node can be dragged freely around the TOC so that it may be placed beneath conceptual topics; however, individual topics for each API cannot currently be rearranged.
Topic Explorer also provides information about the API that each topic node represents and the ability to filter nodes using Sandcastle's API filter (see Filtering Topics
The API type (e.g., namespace
) and the API accessibility (e.g., public
) is shown by a topic node's icon and tooltip. This information is used by the Category
topic filter (see below).
Topics such as All Members
, are provided by the documentation model of the selected Sandcastle presentation style, so they might not appear depending upon the selected presentation. These topics cannot be excluded by simply unchecking them in the tree, however, unchecking them will recursively uncheck all of their child topics, effectively filtering the parent pseudo topics
The following image shows the Category Topic Filter
tab. See the other tabs here
Topic Management Dialog - Category Topic Filter
A topic is included by checking its check box node in the tree view control and excluded by unchecking it. All of the API topics are included (checked) by default if the apiFilter
configuration section hasn't been used.
You can also use the topic filters on the right side of the dialog to include or exclude multiple topics at the same time.
A few options are provided for controlling the behavior of the topic filters.Find/Apply next match only
Checked by default, this setting changes the behavior of the Find
buttons so that only the next match will be located instead of all matches.Show matching topics
Enable this option (default) to display matching topics in the tree as soon as they are found. Each parent node will be expanded to ensure that a matching node is visible. Disabled, the tree will not be changed and the matching items may or may not be visible.Include matching topics
This setting indicates the checked
state of matching topics when they are found by the Apply
button. When checked, matching topics will be checked. When unchecked, matching topics will be unchecked.
Regular Expression Filter
Use the regular expression filter to include, exclude or locate topics by name using a managed-style
regular expression. A link to an MSDN help reference on regular expressions is provided next to a link that pops-up a regular expression quick-help guide, which includes a few examples. You can also choose the regular expression's options
button will locate all matching topics by highlighting them.
button will locate all matching topics, highlight each of them, and ensure that the state of each check box matches the state of the Include matching topics
An icon will appear next to the Find
button after either of the buttons is clicked. The icon's tooltip displays the number of matching topics. The tooltip is automatically displayed for one and a half seconds after the search has completed. Clicking the icon repeatedly will cycle through all of the matching topics, selecting the current node and expanding nodes when necessary. The highlighted color and the icon's appearance differ depending upon whether you have clicked Find
was clicked in Figure 5
and the blue highlights in the tree are the matching topics.
Clicking the icon to cycle through the matching topics can be useful. Use the space bar to toggle (check or uncheck) a matching topic and click the icon to cycle to the next match. Using the icon and the Find
button, instead of the Apply
button, will allow you to manually choose the topics that should be toggled, one at a time.
Use the category filter to include or exclude topics by API category. For instance, to include all interfaces you would first check the Interfaces
check box and ensure that no other category is checked. Then make sure that the Include matching topics
check box is checked to include matching topics (unchecking it will exclude matching topics). Press the Apply
button to apply the changes.
Like the Regular Expression Filter
, an icon will appear next to the Apply
button after it's clicked. The icon's tooltip displays the number of matching topics. The tooltip is automatically displayed for one and a half seconds after the search has completed. Clicking the icon repeatedly will cycle through all of the matching topics, selecting the current node and expanding nodes when necessary.Filtering by accessibility
By checking a combination of Accessibility
and API Types
you can filter on categories such as, public or protected classes and structures
, or internal fields and delegates
, for example.
If nothing is checked under Accessibility
then it is simply not taken into account when matching. In other words, any access type is a match. This is the same as if all access types are checked.
You can also choose an access level without choosing an API type and it will match all APIs with the selected access level. Choosing more than one access level is an OR
operation, just like with API types.
To match protected internal
members you must check protected
since it's treated as a distinct access type. In other words, DocProject does not treat protected internal
members as just being protected or internal
. One caveat is that searching for protected internal
members will also explicitly match protected
-only and internal
-only members as well.
The Saved Filters
tab allows you to save Regular Expression
filters so they can be loaded and applied quickly in the future or, more importantly, applied automatically during each build.Saving Filters
Filters can be added into the list by clicking the Save
button that appears on each of the filter tabs (see Figure 5
above). Alternatively, you can directly edit the XML file in which they are saved, located at Help\Settings\dynamicFilters.xml
. The file does not exist until you add a filter using the dialog and then click OK
, but you can create the file yourself if you want.
column indicates whether matching topics are included or excluded for each filter. When a filter is first saved, the value of this column matches the value of the Include matching topics
search option.Adding Custom Filters
You can create custom filters that apply to the Topic Explorer
window and also during builds (dynamic filters). A working example of a custom dynamic filter is included in the DocProject Extensibility Samples 1.0
To add filters to the list click the Add
and use the dialog to browse to your custom filters.Inheritance Filter
A custom dynamic filter that removes inheritance information is built-in to DocProject. You can add the filter to the list by clicking the Add
button, as indicated above, and then configure it using its custom editor.Importing Filters
Filters can also be imported from a dynamic filters
XML file using the Import...
button. Imported filters are appended to the list and do not replace any existing filters.Editing Filters
column is a place to comment on filters. You can edit the memo directly in the list after you save a filter and it will be persisted along with the filter list when the changes are saved by the Topic Management dialog.
To change the other properties of the filter you can use the Edit
Custom filters can provide their own editor.Applying Filters
Clicking the Load
button on a filter will load it into the appropriate filter tab (i.e., Regular Expression
) and will then show the tab and apply the value of the Include
column to the Include matching topics
search option. The filter will not be applied, however.
button will immediately apply the filter to the topic tree using the current Search Options
and the value in the Include
column, but will not load the filter first.
The Apply All
button will apply all filters to the tree view immediately, top-down. It will not prompt you first, so use this feature with caution.Dynamic Filters
All filters that have a check mark in the Build
column are applied in order, top-down, during a help build. The Apply all filters during builds
option will either check or uncheck the Build
column for all filters so that they have the same value as the option, and each other.
The arrows are used to order the filters, which is important because it allows for the scenario where a particular topic is excluded by one filter, but then brought back in by another, subsequent filter. The filter that re-includes the topic must appear after
the filters that exclude it or else it will remain excluded.Note:
Dynamic filters do not apply to topics that have already been excluded by Sandcastle's API filter; e.g., if you uncheck a topic in the topic tree then a dynamic filter cannot be used to re-include the topic.
Creating XML Documentation
To create external
XML documentation, select a topic in the topic tree, focus the Xml Comments
tab, and select a particular section
to be documented. Then use the XML Documentation Editor
to author the documentation.Figure 6:
Topic Management Dialog - XML Documentation Editor
The list of available XML documentation sections (e.g., summary
) is based on the type of topic that is selected, generated automatically from the information in DocProject's configuration file. The list is also merged with the actual elements found in the existing external
XML documentation files, even if the section is unknown to DocProject.
Some sections may appear multiple times in the documentation for a particular API topic. For example, the exception
section may be added multiple times, one for each Exception
that the API may throw. To add an exception
section to an API, select exception
from the drop-down list that appears above the section list and it will be added to the section list. (If a section doesn't appear in the drop-down list then its association to the API type of the currently selected topic hasn't been specified in DocProject's configuration file.)
To add a custom section to the list, simply enter its name in the text box above the sections list and press Enter
on the keyboard. The new section will appear in the list.
The XML documentation editor supports tags such as <see>
in both source
mode and design
mode. Sandcastle uses these tags when it builds your documentation to apply special formatting or to link to other topics.
link will be created automatically when a topic node is dragged from the topic tree and dropped into the editor, in both source
The editor uses the style sheets of the selected Sandcastle presentation style, with additional rules for formatting XML documentation tags such as, <see>
, for example. The designer style sheet is located in your presentation's Style
folder, which is commonly Help\Styles\TopicDesigner.css
XML documentation that you create on the Xml Comments
tab is saved in individual XML files in the Help\Comments
folder. One XML file is created for each source assembly and one project.xml
file is created to contain the project and namespace summaries. If you prefer you can edit these files using Visual Studio's XML editor.
If you haven't edited any API elements for a particular assembly then its XML file will not exist in the Help\Comments
folder, but you can create it yourself. The name of an assembly's XML documentation file must be the display name of the assembly with .xml
appended to the end or else DocProject will not be able to merge your documentation with the XML documentation files generated by the compiler.
XML documentation that appears in your code using the triple-slash comments (or triple-apostrophe comments in Visual Basic) are not shown in this dialog.
By default, comments created in the dialog overwrite code comments, on a section by section basis; e.g., summary
. But you can change this setting to give code comments precedence instead of being overwritten by selecting KeepSource
for the Merge XML documentation
setting found in Tools
> Active Projects
For more information, see How To Configure DocProject
How It Works
The filtering and TOC-related capabilities of the dialog are based on multiple files in your project, some of which are generated on-demand.TOC
The overall layout of the TOC is stored in the Help\Settings\topics.xml
file. This file does not exist until a conceptual topic is created or imported into the TOC and the changes are saved. You can create this file manually if necessary. It contains a hierarchy of topic
elements that each specify a unique ID, whether the topic should be excluded, and the path to the topic's file, which is relative to the Help\Topics
folder. A placeholder for the auto-generated reference TOC may also be included as an stoc
Dynamic filters on the Saved Filters
tab are stored in the Help\Settings\dynamicFilters.xml
file. This file does not exist until a filter is added or imported and the changes are saved. You can create this file manually if necessary, but letting the UI create it is recommended.
The checked state of auto-generated reference topics corresopnds to the apiFilter
configuration element in Sandcastle's MRefBuilder.config
file, which is included as a project item in the Presentation\Style\Configuration
folder. You can also edit the configuration file manually if necessary.When the dialog is opened
When you open the dialog it may take some time to fill the auto-generated reference topics under the Namespaces
node, so a temporary placeholder exists and the dialog remains responsive to user interaction. In the background, DocProject is using the Sandcastle build engine to build the TOC and filling the tree with topic nodes.Note:
Auto-generated reference topics are only available when the project has one or more sources, which can be external
or project references
. Without sources the Namespaces
node will not be shown.
Basically, all of the steps up to the Build Assembler
are executed in the background. The toc.xml
files that are created by the Sandcastle build steps are then parsed into the tree nodes. The toc.xml
file is used for the layout of the tree and the reflection.xml
file provides most of the information used to construct each topic node. And for each topic node a look-up into the existing apiFilter
configuration section of the MRefBuilder.config
file is performed to discover whether the topic should be included or excluded, by default.
Creating the nodes and populating the tree can take a while for large projects, so please be patient.
Saving the Changes
on the Topic Management
dialog doesn't apply the changes, it only commits them to memory. This allows you to edit the Topic Management
dialog multiple times before you finally save your changes to disc. If you open the Topic Management
dialog again after clicking OK
, but click Cancel
instead, then you will only cancel the changes that you just made and not the changes for which you already clicked OK
. Finally, clicking OK
on the Options
dialog will commit your changes to the project level, but they still will not be persisted to disc until the DocProject
is saved by clicking Visual Studio's Save All
tool bar button or menu item.
DocProject writes directly to the MRefBuilder.config
file, overwriting any existing configuration of the apiFilter
element. Other elements and content in the configuration file remain unmodified.
The dialog attempts to serialize as little as possible to the MRefBuilder.config
file by determining whether child topics will automatically inherit visibility from their parent topic and uses the expose