Specifying a root container for Sandcastle MS Help Viewer output

Question

I'm using Sandcastle Help File Builder to create polished documentation for an SDK. To support Visual Studio's F1 feature, one of the outputs is in MS Help Viewer format. The problem is when we install the package into Help Viewer 1.0 (Visual Studio 2010) or Help Viewer 2.0 (Visual Studio 2012), the documentation is not placed into a root container.

The "API Reference" node shown in the image is the container for the class library itself. While we could rename this node, doing so would not leave any location for us to include conceptual content in addition to the class library reference. Compare this to the location of the equivalent node in the .NET Framework 4 help.

Question: For consistency with other documentation, how can we have Sandcastle Help File Builder produce MS Help Viewer output in a user-specified top-level container for our project, with the current "API Reference" class library documentation being a child of that node?

Answer 1

The root node is actually specified as a conceptual content document.

1. Make sure the documentation project has a Content Layout document.

2. Create a new conceptual content document named MSHelpViewerRoot.aml in the documentation project using the Conceptual template. The contents could look something like this (replace [Guid] with a generated GUID and [My Topic] with your content topic):

   <?xml version="1.0" encoding="utf-8"?>
   <topic id="[Guid]" revisionNumber="1">
     <developerConceptualDocument
         xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
         xmlns:xlink="http://www.w3.org/1999/xlink">
   
       <introduction>
         <para>Welcome to the [My Topic] Reference</para>
       </introduction>
   
       <section>
         <content>
           <para>Select a topic from the table of contents.</para>
         </content>
       </section>
   
       <relatedTopics/>
     </developerConceptualDocument>
   </topic>
   

3. Add the MSHelpViewerRoot.aml conceptual content to the Content Layout document.

   • Under Topic Properties, specify [My Topic] SDK as the Title
   • Under Topic Properties, check the box for Use as MS Help Viewer root container
   • Under Index Keywords, add an entry with Index K and Term(s) [My Topic] SDK

The resulting configuration might resemble the following:

As a final note, in additional to the root node, you may want to do the following:

1. Create a Welcome.aml conceptual content document
   • Add a link to the Welcome document in the <relatedTopics> element of MSHelpViewerRoot.aml
   • Set Welcome.aml as the Use as the default topic element in the Content Layout settings
2. Add a License.aml conceptual content document