Table of Contents
Sandcastle is the tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comments files. The current version is the March 2007 CTP. It is command line based and has no GUI front-end, project management features, or automated build process that you can find in NDoc. I created the
Sandcastle Help File Builder to fill in the gaps and provide some of the missing NDoc-like features that I use most often, as well as provide graphical and command line based tools to build a help file in an automated fashion.
The project is hosted at CodePlex in the Sandcastle Help File Builder project. Go there for the latest release, source code, the issue tracker, and discussion boards.
Using the help file builder provides the following advantages:
- The GUI interface is almost identical to the NDoc interface so anyone familiar with NDoc should be quite comfortable using it.
- You can import several settings from an existing NDoc project to start a new Sandcastle Help File Builder project.
- You can import the assembly and documentation file information from a Visual Studio 2003/2005 solution or project file to start a new Sandcastle Help File Builder project.
- The builder will automatically locate both Sandcastle and the HTML help compilers by looking in the system path and in the Program Files special folder on all fixed hard drives. Properties are also supplied for you to specify the paths in the off-chance that it cannot locate them automatically.
- The builder can produce an HTML 1.x (.CHM) file, an HTML 2.x (.HxS) file, and/or a website. The website output contains an index page and tree view that can be used to navigate the table of content.
- There is built-in support for documenting multiple assemblies and producing a single-help file for them. The assemblies to document can be executable (.EXE) or library (.DLL) assemblies.
- The settings are saved in a project file and the help file can be built from within the GUI or you can add a post-build step to a Visual Studio project that runs the command line tool to build it for you using the same project file.
- The intermediate files used to create the help file are placed in a working folder beneath an output folder of your choosing. They can be automatically removed after a successful build or kept around for further modifications.
- The build process provides full logging and error handling. All output from the build is stored in a text file in the output folder.
- Several of the NDoc features that I use most often have been built into the Sandcastle help file builder including:
- Definition of project summary and namespace summary comments that will appear in the help file. You can also easily indicate which namespaces to include or exclude from the help file.
- The ability to turn off documentation of attributes.
- Automatic determination of the default topic for the help file.
- Inclusion of additional help file content (i.e. your own HTML pages, images, etc). Unlike NDoc, you can also take steps to have the extra HTML pages included in the help file's table of content, indicate which item should be the default page, the order of the entries, and create hierarchical additional content in the table of content.
- You have control over the help file name, title, header text, and footer information such as the e-mail address, copyright text, and copyright URL.
- I have added features to let you control the language of the help file.
- Steps have been taken to make the build process fairly open so that you have a chance to customize it without having to modify the code for the builder application itself.
In addition to the help file builder, the following custom build components are supplied:
- A code block component that extends the
<code> XML comment tag with file inclusion, syntax highlighting, line numbering, collapsible #region and #if/#else/#endif sections, and a copy to clipboard option.
- A post-transform component that can be used to add a logo image to the header of each page, make some minor adjustments to the syntax section, and add version information to the help topics.
- A "show missing" component that adds "missing" notes for missing summary, returns, param, value, and remarks documentation tags and that can also auto-document constructors.
The custom build components can also be used outside of the help file builder in other build scripts and automated tools as well.
See the help file supplied with the help file builder for more information on how to use it. A FAQ is included in the help file that should answer most of the common questions and provide solutions to most of the common issues encountered by users of the help file builder.
To install the help file builder, download the MSI file using the link at the top of the article and run it. It will create a folder and a shortcut to the GUI tool in the
Start | Programs menu. See the supplied help file for information on getting started, links to required resources and other information, setting up your projects to generate XML comments, creating a new help file builder project, common problems and solutions, and expanded information on topics found in this article. When the help file builder is ran, the following window appears. The main form has intentionally been designed to look and function as much like NDoc as possible. The toolbar contains most of the common functions. A
Save Project As option, a
New Project from NDoc Project option, a
New Project from Visual Studio Project option, and a list of the most recently opened projects is also available on the
Project menu. The help builder will automatically load the last used project when opened.
The top part of the form contains a list box showing the list of assemblies that will be documented. The entries display the assembly name and the XML comments filename. The three buttons to the left of the list allow you to do the following:
- Click Add to add one or more assemblies to the list. A File Open dialog box appears in which you can select one or more DLLs, executables, or XML files associated with the items to document. When adding a DLL or an executable, if an XML comments file with the same name is found, it is associated with the assembly automatically. Likewise, if you select an XML comments file a DLL or executable with a matching name is associated with it automatically. If the matching file cannot be determined, it is set to "Unknown" and you can edit the entry to correct it.
- Click Edit to edit the filenames for the selected entry. A new dialog box appears that lets you specify the paths to the two files. If the
CommentsOnly property is set to false (the default), both files must be specified. If CommentsOnly is set to true, only the XML comments file is specified. You can use this option to include a comments file containing project summary and/or namespace settings that are shared amongst multiple help file builder projects rather than specifying them in the Project Summary and Namespace Comments options of each project. See the Shared Settings help topic for more details.
- Click Remove to remove an entry.
See the Project and Namespace Summaries topic for information on setting the project and namespace level summary text and how to limit which namespaces are documented.
NOTE: Only add assemblies and XML comment files that you want documented in the top section. Third-party assemblies, interop assemblies, and other dependent DLLs should be added to the project's Dependencies property. See the Dependencies Property help topic for more information.
The center section of the form contains a property grid that displays the project options. The options are grouped into several categories and are listed alphabetically within them. More information on the properties can be found in The GUI Project Manager section. The bottom section of the form contains an output window that will display the messages from the build process. The View Output in Window option on the Documentation menu will open a resizable window that can be used to more easily view the build log output.
In the form that lets you edit the assembly and XML comment filenames and for the path-related properties in the project, you can enter absolute paths or relative paths. When using the designer popups (accessed by clicking the "..." button to the right of the filename/folder value in the property grid when it is selected), absolute paths are always returned. However, you can edit the returned path to make it a relative path. The key point to remember is that the help file builders (both the GUI and console version) always expect that relative paths are relative to either the folder in which the project file is saved or to the working folder used for the build. The expected relative location will be noted in the description of each affected property. A typical folder layout is shown here:
C:\HelpTest\ Solution folder.
|
+-TestAssembly Application project folder.
| |
| +-Bin
| |
| +-Release Location of assembly and comment files.
|
+-Doc Help file builder project location.
|
|
+-Help The output folder for the help file.
|
+-Working The intermediate working folder used
| during the build.
|
+-DLL Dependencies folder for MRefBuilder
| (if needed).
|
+-Output Help file project compilation folder.
+-art
+-html
+-scripts
+-styles
The example above places the help file builder project in the
C:\HelpTest\Doc\ folder. As such, the relative path to the assembly that will be documented and its comment file is
..\TestAssembly\Bin\Release\. The default output folder for a project is always
.\Help\. If you would prefer the help file to end up in a different location, you can modify it using the
OutputPath property.
The
Prj Summary button in the
Assemblies to Document section of the main form opens a form in which you can enter summary comments that should appear in the root namespaces page of the compiled help file. This is the standard default page unless additional content is defined that is marked as the default page. The Namespaces page is also accessible via the breadcrumb link available at the top of the namespace item help pages in the generated help file. These comments will appear above the list of namespaces and can contain HTML markup (i.e. text formatting, e-mail links, etc). If none are defined, the page just shows the list of namespaces.
The
Namespaces button in the
Assemblies to Document section of the main form allows you to specify which namespaces should appear in the help file and the namespace summaries to display in the root namespaces page and on the help page for each namespace.
Check the namespaces that you want to appear and uncheck those that you do not want to appear. By default, all namespaces in all assemblies are documented with the exception of the global (unnamed) namespace that sometimes appears and contains private module details.
To edit a namespace summary, select the namespace in the list and edit the comments in the text box at the bottom of the form. The comments can include HTML markup (i.e. bolding, e-mail links, etc). If no summary is defined, a red warning note will appear for the namespace on the root namespaces page and above the namespace content in the help page for the namespace itself. When this form is opened, it scans the documentation assemblies for new namespaces and adds them to the list if it finds any. If you build a help file without updating the namespace list, any unknown namespaces will appear in the help file but they will also contain a red warning message indicating that the namespace summary is missing.
Namespaces are never removed from the list even if the namespace no longer appears in one of the documented assemblies. You can remove old namespaces from the list by selecting them and clicking the Delete button.
The following properties are available in the
Path category. These define the location of the tools and the output location of the help file.
This property lets you specify the path to the HTML 1.x help compiler (
HHC.EXE). By default, the builder will try to locate it automatically by searching the Program Files special folder on all fixed hard drives. As such, you only need to specify the path if the build fails with a message stating that it could not be found.
This property lets you specify the path to the HTML help 2.x compiler (
HXCOMP.EXE). By default, the builder will try to locate it automatically by searching the Program Files special folder on all fixed hard drives. As such, you only need to specify the path if the build fails with a message stating that it could not be found.
This property lets you specify where the compiled help file should be placed. The default is to store it in a folder called
.\Help\ relative to the project folder. It is also the location of the temporary
.\Working\ folder used to store the generated build files unless it is changed with the
WorkingPath property.
This property lets you specify the path to Sandcastle. By default, the builder will try to locate it automatically by extracting its location from the system path and, if not found there, by searching the Program Files special folder on all fixed hard drives. As such, you only need to specify the path if the build fails with a message stating that it could not be found.
This property lets you specify an alternate location with a shorter path in which to perform the build if it fails due to long file path names. If not specified, the working folder will be placed under the output path and will be called
.\Working.
The following properties are available in the
Build category. These control the build process.
This property is used to specify whether or not intermediate files created during the build are kept after a successful build or are purged. The default is true to purge the files. If not purged, you will find the files in a
.\Working folder under the project's output path folder. Files that are placed there include the build scripts, configuration files, and the HTML help compiler project output files (scripts, art, HTML pages, the HTML help project, etc). The intermediate files are always retained if the build fails so that you can examine them to find the cause if necessary.
This option allows you to configure build components that support the Sandcastle Help File Builder's plug-in method to interactively set their options. See the
Custom Build Components topic for information on the ones supplied with the help file builder.
This property can be used to specify a list of dependent assemblies and/or folders containing dependent assemblies for use by the
MRefBuilder tool when it generates reflection information for the documentation assemblies. Currently,
MRefBuilder does not resolve references to all assemblies used by a target, especially those found in the Global Assembly Cache (GAC). As such, it needs a pointer to find the files and load them when needed (the
/dep command line option). This property uses a collection editor that lets you choose folder paths, individual files, or GAC references to define the dependencies.
By specifying the dependent assemblies or the folders containing them, the build process can create a folder containing the dependencies for MRefBuilder to use. Paths to the assemblies can be absolute or relative. Relative paths are assumed to be relative to the project folder.
In addition to file and folder dependencies, you can also select assemblies from the GAC. This is useful in situations where an assembly only appears in the GAC and does not have an easily located copy elsewhere on disk. Entries selected from the GAC are prefixed by the identifier "GAC:" and show the fully qualified name rather than a file path. At build-time, the GAC is queried and the necessary assemblies are copied from it to the dependencies working folder.
This property allows you to specify to which .NET Framework version the documentation links for system types should point. The default is to use the most recent .NET version available on the system (currently 2.0.50727). In theory, it is possible to also use Sandcastle to produce help files for .NET 1.1 assemblies. I have not had a chance to confirm that this property actually works as expected. I will provide more details about this property once I have had a chance to test it more thoroughly.
This property lets you specify the type of help file to build (HTML Help 1.x, HTML Help 2.x, a website, or various combinations of the three options). The default is to produce an HTML Help 1.x format file.
Be aware that if an option is selected that produces a website, the output folder will be cleared of all of its current content before the web site content is copied to it. When producing a help file alone, the output folder is not cleared. When producing a website, the following additional files are copied to the root of the output folder.
- *.gif - Several GIF image files are copied that represent the collapsed, expanded, and item nodes in the table of content tree view and the Expand All, Collapse All, and Synch to Content options.
- Index.html - This page is used to contain the frameset for the table of content and the currently selected content page.
- TOC.css - This is the style sheet used for the table of content frame page.
- TOC.js - This JavaScript file contains the code used to implement a basic tree view with collapsible and expandable nodes and is used by the table of content frame page.
- TOC.html - This is the template file used to contain the table of content information. The template is generated during the build and will contain the same entries as the help file's table of content in a matching layout.
This property is present to fix a bug that I ran across. When generating documentation into one help file for multiple assemblies that contain one or more common classes compiled into each of them, you end up with duplicate entries in the table of content and help entries for the common classes. You also get duplicate entries in the namespace help page for each namespace associated with the common classes. To fix this for problem for now, I added this property that causes the builder to strip out duplicate properties from the
reflection.org file generated by
MRefBuilder. It is set to true by default. If you think it may be causing problems, set it to false. If this is fixed in a later CTP, I will remove this option.
The following properties are available in the
Help File category. These control the appearance and features of the generated HTML help file.
When set to true, the default, a binary table of contents is created for the help file. According to the HTML Help Compiler documentation this can significantly reduce the amount of time required to load a very large help document.
These two properties can be used individually or in combination. If only
CopyrightHref is specified, a link will appear in the footer of each page for the specified URL. If only the
CopyrightText property is specified, that message appears in the footer of each page. If both are specified, a link appears in the footer of each page using the text from the
CopyrightText property and the target of the link is set to the URL specified in the
CopyrightHref property. See the
Customizing the Header and Footer Text section for information on how to change the layout of this text.
The value of the CopyrightText property is treated as plain text. It will be HTML encoded where necessary to resolve issues related to the ampersand character and the XML parser. In addition, you can encode special characters such as the copyright symbol using an escaped hex value (i.e. © = \xA9).
If an e-mail address is specified in this property, an extra message is included in the footer of each page with a message saying "Send comments on this topic to" plus the specified e-mail address. The e-mail address is rendered as a click-able
mailto: link. See the
Customizing the Header and Footer Text section for information on how to change the layout of this text.
This property can be used to insert an extra message in the footer of each page. By default, it is blank. HTML tags are supported within the text. See the
Customizing the Header and Footer Text section for information on how to change the layout of the footer section.
This property can be used to insert an extra message in the header of each page. By default, it is blank. HTML tags are supported within the text. See the
Preliminary property for a way to mark all topics as preliminary. See the
Customizing the Header and Footer Text section for information on how to change the layout of the header section.
This property is used to set the title for the help file. This text will appear as the title of the help file's window.
This property is used to specify the name of the HTML help file. This name is used during the build process for a couple of other files so be sure that you do not specify a path or an extension on this value. It should only specify the name part of the file. The extension will always be .CHM and the path is controlled via the
OutputPath property.
If this property is set to true, a Favorites tab will be included in the compiled help file. By default, it is set to false and only the Table of Contents and Search tabs are available.
This property allows you to specify the language to use for the compiled help file. The default is to use the English language resource files. Currently, language resource files are also available for German, French, Spanish, Italian, and Russian. If you specify any other language, the help file will build but you will see a warning in the build output that the selected language resources could not be found and that it is defaulting to the US English (en-US) language files. For more information on creating additional language resource files, see the help file topic by that name. If people are kind enough to supply additional translated files, I will add them in later releases.
This property allows you to specify how the help topics filenames will be generated. There are three separate options:
Guid,
MemberName, and
HashedMemberName. See the help file for full details on the benefits of each naming method.
When this property is set to true, it will mark all topics in the help file with a large, red message "[This is preliminary documentation and is subject to change.]". This is a quick and easy way to mark documentation for beta software as preliminary and subject to change. See the
Customizing the Header and Footer Text section for information on how to change the layout of this text.
This property is used to choose the presentation style that determines the layout and appearance of the help topics. Sandcastle comes with two styles:
Prototype (the default) and
VS2005. The files for each style are located in the
.\Presentation folder under the main Sandcastle installation folder. If you create your own styles, place the folders in the same location and the help file builder will detect them automatically and let you select them in the project.
This property is used to define the type of links used to reference other help topics referring to items within the documented assemblies. It can be set to
None which renders non-clickable links,
Local (the default) which renders normal links defined with anchor tags, or
Index which renders HTML 2.x style MS-Help links. The
Index option is only useful when generating an HTML 2.x help file.
This property is used to specify whether or not a root namespace entry is added to the table of content to act as a container for the namespaces from the documented assemblies. If true, a root
Namespaces table of content entry will be created as the container of the namespaces in the documented assemblies. If false, the default, the namespaces are listed in the table of content as root entries.
This property is used to define the type of links used to reference other help topics referring to framework (SDK) help topics. It can be set to
None which renders non-clickable links,
Index which renders HTML 2.x style MS-Help links, or
MSDN (the default) which renders links to the online MSDN help content for the topic. The
Index option is only useful when generating an HTML 2.x help file.
This property lets you specify which languages appear in the
Syntax section of the help topics and, for the
Prototype presentation style, the dropdown in the upper right of the topics. It can be set to
CSharp,
VisualBasic,
CPlusPlus,
JSharp, a combination of those values,
All to include them all,
Standard (the default) for C#, VB.NET, and C++ only, or to
None to remove the
Syntax section entirely.
The properties in the
Show Missing Tags category define for which help topic elements a red "missing" message will appear if the related tag has not been used where needed or contains no text. These can help you locate help topics that need additional work to fully specify the documentation. In addition to the inserted messages, a warning is written to the log file noting the missing item as well. The following options are available:
- Auto-document constructors
- Show missing <param> tags
- Show missing <remarks> tags
- Show missing <returns> tags
- Show missing <summary> tags
- Show missing <value> tags
See the supplied help file for information on how these properties work.
The properties in the
Visibility category control what appears in the help file and can reduce the help content and get rid of unwanted items, especially when documenting internal and private members. The following items can be included or excluded from the help file.
- Attributes
- Explicit interface implementations
- All inherited members
- Inherited .NET Framework members
- Internal members
- Private members
- Private fields
- Protected members
- The "internal" declaration on protected internal members
- Protected members of sealed classes
Information is written to the log file detailing how each property affected the build. See the supplied help file for details about each property, how some of them interact, and some known limitations.
The
AdditonalContent property is similar in nature to the NDoc properties
AdditionalContentResourceDirectory,
FilesToInclude,
RootPageFileName and
RootPageTOCName. However, the help builder's implementation provides the following added benefits over NDoc:
- You can specify multiple entries consisting of wildcards or individual filenames.
- For each entry, you can specify a specific target folder in the help file project's compilation folder.
- "*.*" wildcard items representing folders are copied recursively. The sub-folder layout is replicated below the target folder.
- All HTML files (*.htm and *.html) are automatically added to the table of content. Sub-folders below the source folder containing HTML files automatically create folder entries in the table of content. As such, it is fairly simple to create a hierarchy of entries in the help file table of content based on the folder structure of the additional content items.
- The help file builder scans each HTML file for some special comment tags. The comment tags can be used to indicate the default topic, exclude a file from the table of content, and set the sort order of items within the table of content group. These are described later.
- The help file builder will also scan the HTML files for XML comment style
<see> tags and will replace them with links to the appropriate help file content (i.e. methods, properties, etc). This is described later.
- The
ExcludeItems option can be set to true on entries to exclude a file or set of files from the additional content. For wildcards, all files matching the wildcard in all sub-folders are also excluded.
- Additional content entries can be placed at the top of the table of content ahead of the namespace entries or at the bottom after the namespace entries using the project-level
ContentPlacement property described later.
- If no additional content is present or none is marked as the default topic, the root namespaces page will be selected as the default topic for the help file.
I believe that this implementation provides a great deal of flexibility and finer control over the layout of the table of content and inclusion of additional content. The following dialog box is used to add additional content to the project. It is accessed by clicking the "..." button to the right of the property when it is selected.
The list box on the left lists the additional content. The property grid on the right lists the properties for the selected entry. The buttons below the list box allow you to:
- Add a folder content item. This adds a wildcard source path that will copy all content from the selected folder matching the wildcard. The path can be absolute or relative. If relative, it is expected to be relative to the project folder. For "*.*" wildcard entries, any sub-folders are also copied to the target folder recursively. For more specific wildcards such as "*.css", only files matching the wildcard are copied, sub-folders are not.
- Add a single file content item. As with the folder content item, the path can be absolute or relative and, if relative, its is expected to be relative to the project folder.
- Delete a content item.
- Preview the table of content that will be generated for the currently defined additional content items. The preview dialog box will also allow you to rearrange the items and set the default topic. The designer will use the current project folder as the base path for resolving relative paths to the content items.
For additional content files, the
DestinationPath property, if specified, will always be a relative path. When creating the help file content, an
.\Output folder is created below the working folder to contain the art, scripts, style sheets, and HTML pages for the content. Additional content will also be placed in this folder. For entries without a destination path, they will be placed directly in the
.\Output folder. For entries with a destination path, the content will be copied to the named folder beneath the
.\Output folder. Any sub-folders beneath the source path folder will also be copied to the destination path recursively. The destination path name can be different from the source path if you want.
All HTML files copied as additional content will automatically be added to the help file's table of content. When the sub-folders of "*.*" wildcard entries are copied that contain HTML files, the sub-folders will also create folder entries within the table of content and the HTML files within them become children of the folder entry in the table of content. This makes it fairly simple to create hierarchical content with matching table of content entries. The table of content will mimic the folder structure on disk.
The help file builder scans each HTML file for several tags and specially formatted comments that allow you to define the title and sort order of the table of content entries as well as which one should be the default topic. The tags can be added to the files manually or you can use the Preview option to visually arrange the items and set the default topic. See the help file for more details.
The additional content help text may need to link to other topics in the help file such as help pages for a namespace, class, method, property, etc. To provide this ability, the help file builder will scan each HTML additional content file for XML comment style
<see> tags. If found, an attempt is made to convert the tag to a link that takes you to the related help page for the indicated item.
Messages are written to the log file indicating how the link was resolved. If no matches are found, a message appears in the log stating that the identifier could not be found and it will be rendered in bold rather than as a link in the help file as is the case with the second example. If a single best match is found, the log message indicates the fully qualified name that was matched and the tag is converted to a link to the associated page in the help file. If multiple matches are found, the log will include a list of all fully qualified names that contained the identifier and the first entry found will be used as the target of the hyperlink.
The help file builder allows you to add custom attributes to the
<pre> tags in additional content HTML files to specify how the text should be colorized. The same attributes defined for the code block component can be used on
<pre> tags with the exception of the
source and
region attributes. For the remaining attributes, the
lang attribute must appear or they will be ignored. See the
Code Block Component help topic for details.
Another benefit of the additional content implementation is that it is possible to replace the stock content that appears in each help file. The stock content is copied from the Sandcastle installation folder and consists of the following:
- The icons\ folder contains stock help file images (i.e. for property icons, method icons, etc).
- The scripts\ folder contains stock JavaScript files.
- The styles\ folder contains stock style sheets.
In addition, the
html\ folder is created to contain the help pages generated from the documentation assemblies. By adding an additional content entry that copies from a source path in your project to one of the stock paths above, you can replace the default entry of the same name. For example, I have customized the style sheet to modify the default font size, remove the indent from code blocks, and add underlines on hyperlinks when the mouse hovers over them. To copy in the custom style sheet, I can add an additional content entry similar to the following:
SourcePath: Styles\presentation.css
DestPath: Styles\
The
ContentPlacement property allows you to define where the additional content items appear in the table of content. By default, they will appear above the namespaces. By setting this property to
BelowNamespaces, you can make the items appear below the namespace entries in the table of content.
The language resource files are located in a sub-folder beneath the
.\LanguageResources folder in the installation location for the Sandcastle Help File Builder. The sub-folders are named using the value returned by the
CultureInfo.Name property (i.e. en-US, fr-FR, de-DE). There are three XML files:
- reference_content.xml contains titles for the various class library parts, filter text, and alternate image text.
- shared_content.xml contains paths to the shared content (art, scripts, and style sheets), code section labels, and customizable text for the header and footer in each page.
- syntax_content.xml contains some programming language limitation messages.
To create resource files for a new language, create a new folder beneath the
.\LanguageResource folder and name it using the culture name as described above. If you are not sure what to name the folder, go to the
Locale Identifier Constants and Strings MSDN topic and locate the locale that you need. The locale name column contains the value to use for the folder name. Once the folder is created, copy the three files from the
.\en-US folder and modify the text for your selected language. If people are kind enough to supply additional translated files, I'll add them to a later release.
How the files are encoded is very important if they contain extended characters. To ensure that the help file builder and the Sandcastle tools properly interpret the encoding within the files, it is best to save the files such that they contain byte order marks at the start of the file for Unicode encoded formats as well as an XML header tag that specifies the correct encoding. In the absence of byte order marks, the encoding in the XML header tag ensures that the file is still interpreted correctly. The supplied default language resource files contain examples of this.
When using entities to represent special characters in the XML language resource files or in the header text, copyright text, etc, use the numeric form rather than the name form as the XML parser will not recognize them and will throw an exception. For example, if you specify Ä (Latin capital letter A with diaeresis) an exception will be generated. To fix it, use the numeric form instead (Ä). This also applies for symbols such as © in the copyright text. Instead, you should use © to get the copyright symbol.
The text for the preliminary documentation warning, header text, footer text, feedback e-mail note, and the layout of the copyright text can be customized by modifying the entries in the
shared_content.xml file. Note that this file is language-specific and you will have to modify the entries for each language that you support. The following entries are available:
- The header entry controls the header text. By default, only the
HeaderText and Preliminary substitution tags are listed in here.
- The preliminary entry controls the text of the preliminary documentation warning. When enabled, this text is substituted for the tag in the header entry.
- The footer entry controls the layout of the page footer. By default, only the
Comments and Copyright substitution tags appear in here.
- The comment entry controls the layout of the "send e-mail" note that appears if a
FeedbackEMailAddress is specified.
- The copyright entry controls the layout of the copyright information that appears in the footer if
CopyrightHref and/or CopyrightText are specified.
To build a help project using the GUI help builder, simply select the
Documentation | Build Project menu option or click the toolbar button. For new projects, you are asked to save the project first so that the build process can determine the correct project folder location for use in resolving relative paths. The build process runs on a background thread and displays output as it progresses in the textbox at the bottom of the form. You can cancel a build by selecting the
Documentation | Cancel Build menu option or by clicking the toolbar button.
Once a build has finished, you can use the Documentation | View Output in Window menu option or toolbar button to view the build process output in a resizable window which makes it easier to see more information. Selecting the Documentation | View Help File menu option or toolbar button will allow you to view the resulting help file after a successful build. The help file and the log file can be found in the folder specified in the project's OutputPath property.
The help file builder project can be added to the solution file so that it can be checked into source control or opened from within Visual Studio. I like to add it as a solution item by right clicking on the solution name in the Solution Explorer, selecting Add | Existing Item, and then selecting the help file builder project. It is then added to a Solution Items folder in your solution.
You can also have Visual Studio open the help file builder project using the GUI tool rather than its default text editor. To do so, right click on the help file builder project and select Open With.... Click Add to add a new program to the list. Enter the path to SandcastleBuilderGUI.exe for your system and enter something like "Sandcastle Help File Builder" for the friendly name. Click OK to save it, and then click Set as Default to make it the default tool for opening the help file builder projects. Click OK to save it. Now, whenever you double-click the help file builder project, it will open in the GUI tool automatically.
To build a help project using the command line tool, run the
SandcastleBuilderConsole.exe executable that can be found in the installation folder. In its simplest invocation, it takes one or more project file names to build and an optional
/v option as command line parameters. The
/v option will display all messages from the tools during the build process. If not specified, only the build step indicators are displayed on screen during the build process. In either case, full output is always saved to the log file. As with the GUI builder, the help file and the log file can be found in the folder specified in the project's
OutputPath property after a build.
Specifying a Post-Build Event to Build a Help File
To use the console version in a post-build event of a Visual Studio project, right click on the project name in the Solution Explorer, select
Properties, and select the
Build Events sub-item. Click in the
Post-build Event Command Line option to enter the command line to run. You can click the
Edit Post-build button to open a dialog with a larger editor and a list of available macros. Below is an example of a common command line script that can be used (lines wrapped for display purposes). Replace the path to the tool with the path where you installed it on your PC. The
IF statement prevents building the help file in debug builds where it may not be needed.
IF "$(ConfigurationName)"=="Debug" Goto Exit
"C:\Program Files\EWSoftware\Sandcastle Help File Builder\
SandcastleBuilderConsole.exe" $(SolutionDir)Doc\TestProject.shfb
:Exit
If you want to see verbose output to the console during the build, you can add the
/v command line option. All messages are always saved to the log file regardless of whether or not this command line option is used.
In a solution with multiple projects that are documented by the same help file builder project, the post-build event should be defined on the last project built by Visual Studio. If the projects are documented individually, you can place a post-build event on each one.
Other Build Tools
Other automated build tools also exist. As long as the build tool supports execution of command line based executables with parameters such as
SandcastleBuilderConsole.exe, you should be able to integrate it with the build process in a similar fashion.
Project Option Overrides
It is also possible to specify project option overrides via the command line and to use a response file to contain a complex list of projects and option overrides to build one or more help files. See the Console Mode Builder topic in the supplied help file for details.
In order to provide the ability to customize the main build steps, I opted to place the scripts used to run the tools and the configuration files in the
.\Templates folder beneath the installation folder rather than embedding them in the executables. This should allow you to further modify them to add steps or modify the final output without having to recompile the build tools. In each file are a set of substitution tags that will be resolved to one of the project properties and, in some cases, a list of files. See the help file for more details on how this works.
The source code is available for download from CodePlex using the link at the top of the article. The source code download includes a demo project that builds a help file for the tools and includes content from this article and other expanded information as additional content. There are several useful design-time classes and controls in the utilities assembly. I will provide more information on them in a separate article at a later date.
Given the architecture of Sandcastle, it is quite flexible and is fairly easy to extend to provide the features that are not there yet. I think the help file builder tools presented here show that quite well. I'm looking forward to the future releases of Sandcastle to see how it progresses.
For a list of planned future enhancements and to make suggestions of your own, see the Issue Tracker at the Sandcastle Help File Builder's project website.
| 03/11/2007 |
v1.4.0.0 - Changes made in this release:
- Added support for the March 2007 CTP of Sandcastle.
- NOTE: The default configurations for the
CodeBlockComponent and PostTransformComponent have changed and must be reset and reconfigured if you customized them via the ComponentConfigurations project option. Line numbering and outlining are now off by default. A new option "Connect code blocks to language filter" has been added to allow connecting the code blocks to the language filter. If enabled (the default), code blocks are shown or hidden based on the language filter setting. If disabled, code blocks are always shown regardless of the language filter setting. Options are also present to set the location of the "Copy" image and the file path for it.
- Made some significant performance improvements. Build times in some cases involving extremely large numbers of topics can be reduced by up to 50% or more. The larger the number of topics to document, the more significant the decrease in build time.
- Optimized loading and saving of the reflection information file and the XML comments files within the build engine.
- Optimized the purge item code and duplicate checking in the name generation code to eliminate unnecessary XPath lookups.
- The processing for the
ShowMissing* options has been moved into a new build component (ShowMissingComponent). On extremely large documentation builds (tens of thousands of topics), the XPath queries that were used to look up the member comments and the information in the reflection file took an extremely long time. By moving the processing to a build component, the amount of information to search is greatly reduced and the time to add missing item comments is now negligible.
- The version information lookup part of the
PostTransformComponent was split out into a new VersionInfoComponent that runs before transformation of the topic occurs. This allows for an optimized lookup of the version information and the whole reflection file does not need to be loaded thus reducing memory usage for large builds and speeding up the searches for version information.
- Added build step timing information so that it is easier to see which steps are taking the longest during a build.
- The console mode builder can now accept project properties as command line options to override or add settings to a project. A response file can also be used to avoid problems with long command lines. See the Console Mode Builder topic for details.
- Added the
WorkingPath property so that you can specify an alternate location with a shorter path in which to perform the build if it fails due to long file path names.
- The following file and folder project properties have been converted from strings to objects. This allows them to be persisted as paths relative to the current project location rather than as absolute paths at your choosing. In addition, environment variables such as
%DXROOT%, %WINDIR%, etc. can be specified in the paths and they will be expanded at build time to the value of the specified environment variable. Properties affected:
- SandcastleProject.HtmlHelp1xCompilerPath
- SandcastleProject.HtmlHelp2xCompilerPath
- SandcastleProject.SandcastlePath
- SandcastleProject.WorkingPath
- DocumentAssembly.AssemblyPath
- DocumentAssembly.XmlCommentsPath
- ContentItem.SourcePath
- DependencyItem.DependencyPath
The OutputPath property is still a string. If relative, it is always relative to the project folder and thus should not point at the prior location if the project is saved in a new folder. For similar reasons, the DestinationPath property of additional content items has also been left as a string.
All fully qualified paths in the affected properties in projects created by prior versions of the help file builder will become relative paths automatically when opened in the latest version. If you need a fixed path, expand the property and set the IsFixedPath property to true so that it is saved as an absolute rather than a relative path.
- It is now possible to resolve project option values and shared content items in additional content files. See the Project Properties and Shared Content help topic in the Additional Content Settings section for details.
- Fixed a bug in the code to resolve links to namespace content from additional content that caused it to add too many relative path parts to the URLs. Fixed a bug that caused it to miss the default page setting if the page was associated with a folder. Also fixed a bug that caused it to ignore the page if it was associated with a folder and it was the only file in the folder.
- Fixed a bug in the code colorizer caused by the description for the collapsed region not being HTML encoded. Also fixed up the definitions so that it doesn't colorize preprocessor text within quotes and comments and handles XML attribute names containing colons.
- Fixed the
CodeBlockComponent and the code colorizer so that they recognize VB.NET style #Else If, #End If, and #End Region statements.
- The code colorizer now renders a "Copy" icon and text to the right of each title line on the code blocks and allows you to copy the code to the clipboard. The code is copied as plain text without the highlighting and line numbers if used. Default titles are also used on code block that do not have a title. The default title is based on the language specified.
- Modified the the C++ comments fixup code so that it only strips out the unnecessary characters if they appear in a declaration involving the
System.Collections.Generic namespace.
- The
PresentationStyle property now uses a type converter that allows you to select any folder under the .\Presentation folder in the main Sandcastle installation folder. This allows you to create custom versions of the Prototype and VS2005 styles using different names and select them for use from within a help file builder project.
- The build process now tries to delete the help file first if it exists so that it stops immediately if the help file is open and cannot be overwritten.
- Made the file extension checks case-insensitive when adding assemblies and comments files to the project and when examining additional content files during the build.
- When documenting internals, private fields backing events are now removed as they can never be documented with comments.
- Removed extraneous paragraph tags from the formatted footer replacement tag values.
- Modified the
comments shared content item so that the e-mail link in the page footers now appends the current topic's title to the help file's title for the e-mail's subject.
- Added a FooterText property to the project that lets you add additional text to the footer of each page without having to modify the shared content file. The text is inserted at the start of the
footer shared content item.
- The post-transform component now turns off all file attributes when copying the highlighter and logo files so that they can be deleted at the end of the build when
CleanIntermediates is set to true.
- Added
placement and alignment attributes to the logoFile element of the post-transform component. This allows the logo to be placed to the left, right, or above the topic title. When placed above the topic title, it can be aligned to the left or right or centered.
- Moved the version information text to the end of the location information shared content items. The
PostTransformComponent now moves the location/version text to the end of the footer in the Prototype style.
- Added a Delete button to the Namespaces dialog that lets you remove old namespaces from the list that no longer appear in the assemblies.
- Added
Help1xAndHelp2x and Help1xAnd2xAndWebsite options to the HelpFileFormat project option.
- Added an
ExcludeItems property to the additional content items. If set to true, the file or files matching the source path are excluded. If used with a wildcard source path, all matching files in sub-folders are excluded as well.
- Thanks to Dessiatov Anton for providing Russian translations for the language resource files. See the FAQ for a fix that must be made to one of the Sandcastle transformations for the HTML content in order to work with them correctly.
|
For a full list of all changes in prior versions see the help file supplied with the application.
