Deselected topics being reselected

Topics: General Questions
May 19, 2009 at 5:32 PM

How do I stop docProject from selecting sections to include in the docs? For example, we don't want the fields to show up for most parameters so I've deselected them in the Topic Explorer but when I close the project and reopen it the next day, the Fields checkbox is selected again.

What I tried to do was deselect each class, then manually select All Members, .ctor, Methods, and Properties. I did this through the entire project, then closed down for the day. When I reopened the project this morning, all the Fields were reselected. I really don't want to have to manually deselect all the Field checkboxes before I build, so how do I get docproject to stop reselecting it?

May 20, 2009 at 2:02 AM


After you check/uncheck topics in Topic Explorer and click Visual Studio's Save All button, (i.e., not the button that saves the current document, the button that saves the entire solution), Topic Explorer will persist your changes to the project's MRefBuilder.config file, which is located in your project's Help\Presentation\Style\Configuration\ folder.  This file is used by Sandcastle's MRefBuilder program to filter out unwanted APIs early in the build process.

Pseudo topics; e.g., Fields, Properties, Methods, cannot be filtered in this manner because they are not APIs - they are introduced into the documentation later in the process, after MRefBuilder has been executed.  However, unchecking pseudo topics will automatically uncheck all of the topics beneath them.  These filter changes to the sub-topics will then be persisted in your project's MRefBuilder.config file when you save the solution.  (Open the file in VS and look for the <apiFilter> element.)

After restarting Visual Studio, open Topic Explorer and it will automatically load and apply the filter from your project's MRefBuilder.config file.  If you see any differences please report them with steps to help me reproduce the problem.  If the API filter looks fine but Topic Explorer is not reading it, then check the Windows Application event log for errors and send me the <apiFilter> element so that I can make sure it's valid.

Note that because pseudo topics are not saved in MRefBuilder.config they are always marked as included by default.  This means that they will be checked every time you load the project.  However, the topics underneath them should retain their filtered state from the MRefBuilder.config file.

Also note that if all of the topics underneath a pseudo topic have been excluded, then Sandcastle will not include the pseudo topic during your documentation build.

Alternatively, you can create custom filters for your project in the Topic Filters tool window (accessible via a toolbar button in Topic Explorer).  DocProject will apply your custom filters during each build if you save them by clicking the Save button.  You'll then find your saved filters on the Saved Filters tab (make sure that the Build column is checked for your filter otherwise it will just be saved without being applied during builds).  Filtering this way is more flexible and can help you to workaround issues you may be having with the Topic Explorer filtering.

- Dave