DocProject for Sandcastle

New Post: Code Example: Reference source code file in project?

davedev — Fri, 04 Jul 2008 10:13:55 GMT

Hi Mike,

Thanks. I'll definitely look into adding the external code snippet support for the next release.

- Dave

New Post: Code Example: Reference source code file in project?

mdbell — Fri, 04 Jul 2008 08:34:07 GMT

Thanks for your extensive help, chaps.

There was indeed a misunderstanding on my part as I was looking for SyntaxComponents.dll in Eric's download.

I should say you have both produced a fine set of tools, by the way!

Dave, colouring of code comments is not an issue for me so a native B&W code snippet importer in DocProject would be an excellent addition. I've been using DocProject for a couple of weeks now and (for a programmer documenting a set of web services) it's the only thing that has been "missing" out of the box.

// Mike

New Post: Creating Xml comments for large number of files

davedev — Thu, 03 Jul 2008 19:25:30 GMT

Hi,

Have you looked at GhostDoc?

- Dave

New Post: Creating Xml comments for large number of files

amccool — Thu, 03 Jul 2008 17:16:52 GMT

I have a project with a large number of files/classes. Most of these are public (DTO's), but were delivered without any xml comments. Obviuosly I get a huge warning list when I compile the project. Does anyone know of a tool which could help generate a super basic xml comment for all the public classes, and properties? This is C# code BTW

Thanks

New Post: Code Example: Reference source code file in project?

davedev — Thu, 03 Jul 2008 15:50:55 GMT

Hi Eric,

Thanks for the reply.

I think the problem here is actually just a simple misunderstanding. The SyntaxComponent problem isn't with DocProject, it's with Visual Studio 2008. In the other thread I linked to my bug report on Microsoft's connect website which explains the details, but basically when you use reflection in VS 2008 to load a type, all assembly references are resolved immediately so delayed-loading is not supported. Since SyntaxComponent is not located in the VS probe path or the GAC, it's not found and an error occurs. Registering SyntaxComponents.dll as a dependency in DocProject's configuration file easily fixes the issue since DocProject handles assembly resolution itself for all registered dependencies.

Anyway, that issue only affects using DocProject's build component stack editor to add your components. They can be added manually to the configuration files without any issues.

- Dave

New Post: Code Example: Reference source code file in project?

EWoodruff — Thu, 03 Jul 2008 15:09:54 GMT

The SyntaxComponents assembly is not part of SHFB, it's part of Sandcastle so it isn't distributed by me. The main problem here seems to be that DocProject is trying to load the assembly in some way that requires extra definitions on its part to handle the dependencies.

You don't need the full SHFB download for the standalone components. There is no installer for the standalone build components because, well, they are standalone so there's really nothing to "install". You just unzip it to a location of your choice and edit the sandcastle.config and conceptual.config files to include the components were they need to be. The paths in the component configurations should point to were you placed them. There is a help file provided that describes the components and their configurations and where to place them in relation to the other components if doing it by hand.

With SHFB, integration of third-party build components is automatic and is handled at build time via the SandcastleBuilder.components.config file supplied with the components. DocProject could probably use that to add the component to its config files too. If you're doing it by hand, you need to edit the configuration files yourself but the default configuration supplied within the component .config file can be used as a starting point.

Eric

Updated Wiki: Latest Release Notes

davedev — Thu, 03 Jul 2008 14:18:01 GMT

Required Software
Optional Software

Installation
.NET Framework Reflection Data
Known Issues

All Versions
DocProject for Visual Studio 2005
DocProject for Visual Studio 2008

Support for Visual Studio Express editions
Source Code

DSZip Utility

Getting Started
Help
Feedback

Introduction

This document contains important instructions and information relating to the installation of DocProject 1.11.0 Release Candidate. Please read this carefully before installing DocProject or any of its dependencies.

Important: Existing DocProjects and DocSites created by DocProject 1.10.1 and earlier are not compatible with this release. You must create a new project and use the Import Topics and Settings step in the New Project Wizard to perform the update automatically.

For a list of new features added to this release, see the New Features section on the home page.
For information about API and architectural changes, including notable breaking changes, refer to the changeset comments in the Source Code area of this website.

Additional Software

DocProject requires additional software to be downloaded and installed separately. Some of the software is optional depending upon the features that you will use.

Please read Required Software and Optional Software below to determine which software you must install before installing DocProject.

Required Software

The following software is required by DocProject:

Visual Studio 2005 or 2008.

The latest DocProject release only provides a single installer but supports both versions of Visual Studio.
Service Pack 1 is also required for Visual Studio 2005.
Visual C# Express and Visual Basic Express may be used instead (see below for details).
English only; other languages may not be compatible.

The Sandcastle May 2008 Release is required to use the Sandcastle and Sandcastle/Deployment build engines. (These are the only engines provided by DocProject.)

Required Software for DocSites
In Visual Studio 2005 the following software is required to use the DocSite Templates (a flavor of DocProject Templates that build an ASP.NET documentation website):

ASP.NET 2.0 AJAX Extensions 1.0.

Note: Visual Studio 2008 does not require a separate installation of AJAX Extensions because the .NET 3.5 Framework has the AJAX assemblies built-in.

Supported Browsers for DocSites
The DocSite templates build a website that has been tested for compatibility with the following web browsers only:

Firefox 2.0.0.9
Opera 9.24
Windows Internet Explorer 7.0.6000.16575
Microsoft Internet Explorer 6.0.2900.2180; SP2

Earlier versions of MSIE such as 5.5 have not been tested and might not be compatible.

Optional Software

Optional software is recommended, but not required for DocProject's standard feature set.

Presentation Patch
Download and apply the latest patch from Sandcastle Styles before using DocProject.

This patch provides bug fixes for common issues with Sandcastle's presentation styles and also adds additional features that are supported by DocProject.

Web Site Projects
Download the latest release of Documenting Web Projects to get new code providers that make it easy to extract assemblies and XML documentation files from Web Site projects.

Note: This download is not required for Web Application projects, which can be added to DocProjects and DocSites as project references instead of as external sources.

For more information about Web Site projects, see How To Build Help For a Web Site Project.

Compiled Help
DocProjects and DocSites can automate the process of building compiled help 1.x and 2.x if the following software is installed:

Help 1.x: HTML Help Workshop
Install the workshop compiler if you want DocProject to build a distributable help package (.chm file) that can be opened on any Windows system, stand-alone or included as part of the documented application for context-sensitive help.

Help 2.x: Visual Studio SDK (2005, 2008)
Install the SDK if you want DocProject to build a help collection (.HxS file) that can be merged with Visual Studio's help collections. This is useful for add-in, control and package developers that integrate their products into Visual Studio.

Important SDK Installation Notes
When you install a Visual Studio SDK you must manually delete the DXROOT user environment variable that the installer creates for an older CTP version of Sandcastle.

Windows 2003/XP Instructions

Open System Properties: Start > Control Panel > System or right-mouse click the My Computer icon and select Properties.
Go to the Advanced tab.
Click the Environment Variables button.
In the User variables list, highlight the DXROOT variable and click Delete.
Ensure that the DXROOT variable exists in the System variables list and that it specifies the root installation directory of the latest Sandcastle release (commonly, C:\Program Files\Sandcastle\).
Click OK three times to exit all of the dialogs.

Windows Vista Instructions

Open System Properties: Logo > Control Panel > System or right-mouse click the Computer icon and select Properties.
In the pane on the left click Advanced system settings
Go to the Advanced tab.
Click the Environment Variables button.
In the User variables list, highlight the DXROOT variable and click Delete.
Ensure that the DXROOT variable exists in the System variables list and that it specifies the root installation directory of the latest Sandcastle release (commonly, C:\Program Files\Sandcastle\).
Click OK three times to exit all of the dialogs.
Close the System window.

Installation

The DocProject installer provides Visual Studio templates, a Visual Studio Add-In and a Sandcastle plug-in for DocProject. After installing DocProject it will be ready to use in all supported versions of Visual Studio; however, Sandcastle and other tools must be installed separately.

To install DocProject:

Download the latest release
Close all running instances of Visual Studio.
Double-click the installer to begin the installation.

Vista users: right-mouse click and select Run as administrator instead.

When presented with the option to choose the target versions of Visual Studio, only the versions that are detected on your system and supported by DocProject will be listed.

Note: Express editions are not listed separately. For example, if you choose to install for Visual Ssudio 2005, that includes all supported versions of Visual Studio 2005 that you have installed on your system.

The DocProject installer can install DocProject for Everyone or Just me in the following versions of Visual Studio if they are detected on your system:

Visual Studio 2005 and 2008 Standard or higher
Visual C# 2005 and 2008 Express
Visual Basic 2005 and 2008 Express

Detailed instructions for installation, configuration and general usage can be found in the How To... wiki.

.NET Framework Reflection Data

The latest Sandcastle installer contains the .NET Framework reflection data files that are used to link to MSDN content.

Important Note for DocProject 1.8.0 RC Users
When DocProject 1.8.0 RC was released the Framework reflection data files had to be generated manually by end-users, so DocProject automated the process.

The reflection files that DocProject generated were saved under Sandcastle's installation folder, however, uninstalling both DocProject and Sandcastle does not remove them. You must manually delete the %DXROOT%\Data\Reflection\ folder and all of its subfolders before installing the latest release of Sandcastle; otherwise, if you've already installed the latest version of Sandcastle, then you must reinstall Sandcastle after manually deleting this directory.

%DXROOT% is commonly, C:\Program Files\Sandcastle.

Auto-generation
DocProject is configured to automatically generate these files the first time a DocProject or DocSite is built if they do not exist, however there are some things to be considered:

The framework reflection data files must have a document model applied, but since DocProject will only generate these files once, the model for the Sandcastle presentation style that you've chosen for your project will be used and all subsequent projects, regardless of the presentation style, will use the original framework reflection files.
If the build fails before DocProject has completed generating the framework reflection data, then you must delete the %DXROOT%\Data\Reflection\ folder and start again. DocProject will not attempt to create the missing framework reflection data so if you do not delete the folder then DocProject will assume that the data is already present.

More information can be found in a thread on the MSDN forums: http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2217724&SiteID=1.

Using Multiple Presentations Styles
If you plan on using different presentation styles then you may want to enable DocProject to build distinct reflection data files for each presentation. To enable this feature you must install DocProject and then:

Open DocProject's configuration file, commonly found at C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config.

Note: Do not confuse it with the DocProject.exe.config file.

For each registered presentation (each <add> element under the <presentations> element), set the fxReflectionDataDirectory attribute to the name of a subfolder that DocProject will create under %DXROOT%\Data\Reflection for the presentation's framework reflection data.

Note: If you want to share the same framework reflection data between two presentations, such as Visual Studio 2005 and Sandcastle Hana, simply use the same subfolder. For example, fxReflectionDataDirectory="VS2005".
Note: If the specified subfolder already exists then DocProject will not build the framework reflection data for that particular presentation style.

Uncomment the three <add> elements at the end of the configuration file (after the "Update .NET framework reflection data path" comment).
For each previously uncommented <add> element, set the replaceWith attribute to the value specified in the corresponding presentation's fxReflectionDataDirectory attribute, which you set previously.

Note: Specify the full path in the replaceWith attribute; e.g., %DXROOT%\Data\Reflection\VS2005.

Generating Framework Reflection Data Manually
If you do not want DocProject to generate reflection data automatically for any presentation style, you must install DocProject and then:

Open DocProject's configuration file. (See above for more information.)
Set the generateFrameworkReflectionData attribute to False.

Known Issues

Some of the following issues cannot be resolved manually and others will be resolved in subsequent releases. Fixes will be noted as they become available.

All Versions of DocProject

The following issues apply to all versions of DocProject:

Docsite Templates, Windows Security Issue
This issue affects the DocSite templates only, in any language.
Sandcastle/Deployment and FTP
When using the Sandcastle/Deployment build engine provider, if you specify an FTP url for the target location then the source directory structure must already exist on the target machine.
Improved Vista Support
DocProject has strict CAS requirements that require administrative privileges, which means that Visual Studio must be started with Run as Administrator on Vista when UAC is enabled.

DocProject for Visual Studio 2005

The following issues only apply when DocProject is used in Visual Studio 2005:

ClickOnce Sources
Projects that build an executable that is deployed using ClickOnce cannot be referenced by other projects in Visual Studio, so they must be referenced as external sources instead. See the following article for more information:

ClickOnce applications cannot be project references

DocProject for Visual Studio 2008

The following issues only apply when DocProject is used in Visual Studio 2008:

There are no known issues that are specific to this version of Visual Studio.

Support for Visual Studio Express editions

Support for Visual Studio Express editions is limited because they do not allow add-ins. However, the DocProject External UI (DocProject.exe) can be used to configure and build DocProjects and DocSites that are created in express editions.

DocProject supports the following features in express editions of Visual Studio:

identical installation as the full version, except that the Add-In is not installed in express editions.
support for both Visual Basic and Visual C# DocProject templates, depending upon the versions of Visual Studio that are installed.

Note: DocSite templates are not currently supported in Visual Web Developer Express.

the New Project Wizard, which starts when a new DocProject is created.
the MSBuild task that starts the help build process inside Visual Studio and outside, such as on the command-line or a build server.
a custom Build Process Component, without Visual Studio automation capabilities.
configurable project folders and items such as presentation and configuration files for Sandcastle (e.g., sandcastle.help1x.config).

The following features are currently unavailable to express editions but are available using the DocProject External UI:

the ability to cancel help builds.
partial and skipped builds.
tools options pages for managing build engines and active project settings.
content and topic management dialogs.
the Include Project Output Dialog that allows users to easily import project items after each build.

Source Code

The DocProject installer does not provide the source code anymore. To download the source code, visit the Source Code area of this website.

DocProject's Visual Studio 2008 solution and projects have been tested on multiple systems in an attempt to make them usable, out-of-the-box.

For help using DocProject's Visual Studio solution and projects, see How To Use The Source Code.

DSZip Utility

Download and install the DSZip utility if you plan on using the supplied Visual Studio solution to build the Visual Studio Content Installer file (.vsi) or the Windows Installer package (.msi) using the DaveSexton.DocProject.InstallActions project.

If you are not planning on using the solution file or projects to build the installers, or if you're not even planning on using the source code at all, then you do not need the DSZip utility.

Note: DSZip version 1.1.0 is provided on the release page. This is the same version that was provided in previously releases of DocProject, so if you've already installed it then there is no need to download it again.

For more information, see How To Use The Source Code, Projects.

Getting Started

After reading this article and successfully installing DocProject and its dependencies, see About DocProject, Getting Started if you are a new user.

Help

For information about how to properly request assistance and how to resolve issues on your own, see How to Diagnose and Resolve Issues.

Links to documentation can be found in the Wikimap.

Various help topics and tutorials can be found in the How To... wiki.

Feedback

Thanks for your interest in DocProject. Any feedback you can provide will be appreciated.

What can I do to improve DocProject for you or your organization?

New Post: Code Example: Reference source code file in project?

davedev — Thu, 03 Jul 2008 11:38:32 GMT

Created feature request:

Ability to Pull in Code Snippets from Buildable Source Code
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=17241

- Dave

New Post: Code Example: Reference source code file in project?

davedev — Thu, 03 Jul 2008 11:32:44 GMT

Hi Mike,

Your thread incorrectly says that one should use the Standalone Sandcastle Build Components download
This download does not include either an installer or the SyntaxComponents DLL that you mention

The download is a zip file that contains all of the custom build components, which should be everything that you need. There's no installer, so I assume that you can probably unzip the contents anywhere. SyntaxComponents.dll is a Sandcastle assembly though, so it's already on your computer. (Look in the ProductionTools folder in the Sandcastle installation directory.)

Instead, you have to download the entire Sandcastle Help File Builder Installer

I don't think so. Nobody else seems to have had to install the full program just to use the standalone build components in DocProject. At least nobody mentioned that to me.

That kind of makes me wonder what value there is in the Standalone Sandcastle Build Components download if it can't actually be used without the full Sandcastle Help File Builder Installer

I would have to agree if it were true, although I don't think that your assumption is accurate.

This is getting pretty complicated, actually, as it seems that yet further "code providers" need to be downloaded

I'm not sure what you are referring to by code providers. Are you attempting to document a Web Site project perhaps? If so, the limitations are due to the design of Web Site projects in Visual Studio, so there's nothing else that can be done about it other than to use a custom code provider or follow my recommendation and use a Web Application project and/or a class library instead.

the SyntaxComponents needs configuring in the build stack, it has to be added at a specific point in the stack (where?)

The SyntaxComponents.dll assembly does not provide any build components (it probably should have been named SyntaxGenerators.dll). Although, if you're referring to Sandcastle's SyntaxComponent build component, which exists in BuildComponents.dll in the ProductionTools folder, that's already in the reference stacks as a subcomponent to the first If component. To add SyntaxComponent to the conceptual stacks you must edit the configuration files manually (Help\Presentation\Style\Configuration\conceptual.helpNx.config).

I guess you could just copy the <component> element for the SyntaxComponent from within the  section of the reference stacks, but I can't say for sure whether that's even required in the first place since I don't know how the code block component works.

You're probably better off asking about this in the SHFB forum. If you find out what the requirements are to use the code block component in conceptual stacks then feel free to ask me how to perform the necessary tasks to get it working in DocProject. (Note that getting it to work in DocProject should be exactly the same as the requirements for getting the component to work using Sandcastle by itself, without any automation tool. So if the components work outside of SHFB and DocProject, then they should also work inside of DocProject as well without any extra effort.)

the application requires new <compiler> configuration sections

Again, I think you're referring to a Web Site project, to which these limitations are inherent. Some manual configuration, to produce output that may be used by Sandcastle, is required by design in Web Site projects and so is unavoidable unless you use a different project type.

And then there is the matter of intellisense for the <code> element showing up correctly in DocProject: "source" is not a valid attribute

If you're referring to the MAML code element as used in conceptual topics, the list of supported attributes that are shown by IntelliSense are taken from the MAML schemas provided by Sandcastle.

The source attribute, presumably, is an extension to the schemas provided by the code block component. If you want IntelliSense to be accurate for the custom build components that you're using then you must update the MAML schemas manually. This is unavoidable since the MAML schemas are provided by Sandcastle, which obviously does not support the various features of custom build components.

Note that I'm working on releasing a preview of my MAML editor within the next week (hopefully by Monday) so issues with IntelliSense for conceptual topics in Visual Studio's XML editor should become a thing of the past.

<wish> [snip]

I agree that being able to pull in code snippets from source code is probably a useful feature of the code block component. Although, I don't think that you need to install SHFB to get it working; the task of incorporating the component into DocProject projects shouldn't be a difficult one. The code block component also offers other features, such as code coloring, but frankly I've never seen enough value in code coloring snippets to where I've wanted native support for it in DocProject, and so I hadn't intended on reinventing these features.

Regardless, I'll add this as a feature request and see if I can get something working for the 1.12 release. My goal will be to have DocProject natively support pulling in code snippets from actual source code files. (Again, I agree that this seems like a useful feature - especially considering how easy it is to add buildable code directly to DocProjects and DocSites.) However, I don't plan on adding support for code coloring or any other features of the code block component (if there are any) for this next release. Maybe I will in a subsequent release though if there's enough of a demand for it.

Thanks for the feedback,
Dave

New Post: Code Example: Reference source code file in project?

mdbell — Thu, 03 Jul 2008 09:37:22 GMT

Thanks Dave.

Your thread incorrectly says that one should use the Standalone Sandcastle Build Components download.

This download does not include either an installer or the SyntaxComponents DLL that you mention. Instead, you have to download the entire Sandcastle Help File Builder Installer. That kind of makes me wonder what value there is in the Standalone Sandcastle Build Components download if it can't actually be used without the full Sandcastle Help File Builder Installer!

This is getting pretty complicated, actually, as it seems that yet further "code providers" need to be downloaded, the SyntaxComponents needs configuring in the build stack, it has to be added at a specific point in the stack (where?), the application requires new <compiler> configuration sections. And then there is the matter of intellisense for the <code> element showing up correctly in DocProject: "source" is not a valid attribute.

<wish>
It strikes me that nearly anyone who is documenting a .Net project is going to want to include code examples and those code examples are best maintained in source code form. Life would be so much easier if DocProject supported this directly rather than having the user fully install a competing product and spend the next week figuring out how the two should work together!
</wish>

Updated Wiki: Sandcastle Help

davedev — Wed, 02 Jul 2008 18:43:22 GMT

Sandcastle Help

Introduction
Key Points

General Information
Usage
Output
Common Issues

Build Scripts
Community Projects

Open Source GUIs for Sandcastle
Supplementary Community Projects

Related Downloads
Xml Documentation
Conceptual Documentation Using MAML
Online Resources

Introduction

This document provides important information and links to various online resources for learning about Microsoft Sandcastle.

Key Points

Here are some key points that you should know about Sandcastle before you get started:

General Information

Sandcastle is currently released on CodePlex (http://www.codeplex.com/Sandcastle).
Sandcastle is also bundled as an older community technology preview (CTP) with the Visual Studio 2005 and 2008 SDKs.
Sandcastle is based on Microsoft's internal tools that are used to build documentation for Visual Studio and the Microsoft .NET Framework.
In the past, a new CTP version of Sandcastle was released approximately every 1 to 3 months. This pattern is expected to continue.

Usage

Sandcastle is not a single executable program but is actually a set of programs and XSL transformations that must be used together.
Sandcastle is extremely flexible and offers many configurable features.
Sandcastle's build process can change depending upon the desired output, format and presentation style, so there isn't one universal process that can meet everyone's needs.
Sandcastle can be used in various scripts such as batch files, MSBuild and PowerShell. (See Build Scripts below for more information.)
Sandcastle provides an example graphical user interface (GUI) that automates an MSBuild script, but it does not provide Visual Studio integration and many of the desirable features that users have come to expect from help authoring tools (HATs); although, the open-source community does. (See Open Source GUIs for Sandcastle below for more information).

Output

Sandcastle supports different presentation styles, including one that looks like the documentation for Visual Studio and the Microsoft .NET Framework.
Sandcastle produces XML-based HTML topic files using two different processes, which can be combined together to produce mixed documentation:

Conceptual documentation (e.g., custom topics, walk-throughs, how tos, troubleshooting) is built from Microsoft Assistance Markup Language (MAML). (See Conceptual Documentation Using MAML below for more information.)
Auto-generated reference documentation is built for managed and unmanaged application programming interfaces (APIs).

Reflection information for managed assemblies can be generated automatically by Sandcastle's MRefBuilder.exe program.
Reflection information for unmanaged libraries must be generated by a third-party tool. (AjaxDoc is one example.)
Sandcastle can optionally integrate XML documentation from code comments or external tools into auto-generated topics. (See Xml Documentation below for more information.)
Sandcastle will pass through many common HTML tags in XML documentation (code comments), such as <p>, <img>, <strong>, etc.

Sandcastle itself does not build compiled help (e.g., HTML Help 1.x, 2.x) but the installed build scripts enable this scenario out-of-the-box with some additional software. (See Related Downloads below for more information and links to downloads.)

Common Issues

When just starting out it's likely that you'll run into a few common issues when using Sandcastle:

Internet Access
Sandcastle resolves links to online MSDN topics using a web service, which requires Internet access. This feature can be disabled in the sandcsatle.config file at the cost of hyperlinks to MSDN content in your documentation. For more information, see this blog post.

Proxy Server
If a proxy server is being used for Internet access then Sandcastle must be configured appropriately. For more information, see Sandcastle and Proxy Servers.

Missing Code Comments in Documentation
By default, all of a project's XML documentation is expected to be in a single file named, comments.xml. If you have multiple XML documentation files then place them in a new folder named, Comments and adjust sandcastle.config to use a wild card instead, as in the following example.

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
           assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
  <index name="comments" value="/doc/members/member"
         key="@name" cache="100">
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727"
          recurse="false" files="*.xml" />
 
    <data files="Comments\*.xml" />  <!-- This line was modified -->
 
  </index>
  <copy name="comments" source="*" target="/document/comments" />
<components>

For more information, see this blog post.

Visual Studio 2005 and 2008 SDKs install a DXROOT environment variable for an older CTP
The SDKs install an older version of Sandcastle on your system and then create a DXROOT user environment variable pointing to the installation folder. This environment variable is vital for Sandcastle to work. However, newer versions of Sandcastle create it as a system environment variable. Since the user variable has precedence, the older CTP version of Sandcastle will be used when building on the command-line and when using automation tools.

This causes several related issues that sometimes aren't so obvious. It is highly recommended when installing an SDK that you take action before using Sandcastle. To fix this problem, delete the DXROOT user environment variable that was created by the SDK installer. Also, ensure that the DXROOT system environment variable was created by Sandcastle's installer and that it points to the Sandcastle installation folder; commonly, C:\Program Files\Sandcastle\.

Build Scripts

Microsoft has not provided formal documentation yet, however the installation comes with a few scripts that you can use to learn about Sandcastle's build process and tools and to get started building documentation right away:

Graphical User Interface (GUI): Examples\generic\SandcastleGui.exe
MSBuild project: Examples\sandcastle\build.proj
Command-line batch script: Examples\sandcastle\build_Sandcastle.bat
Windows PowerShell script: ProductionTools\scbuild.ps1

Community Projects

Several products have been developed by the user community to improve Sandcastle's usability and to enhance its feature set.

Open Source GUIs for Sandcastle

The following open source projects provide GUIs for automating Sandcastle. They allow you to easily configure settings and build documentation with various output types:

DocProject: Visual Studio 2005/2008 integration using MSBuild project templates, an Add-In and GUIs.
Sandcastle Help File Builder: A popular NDoc-style GUI and console-mode application with custom build components.
Sandcastle GUI: Another popular GUI for Sandcastle.

Supplementary Community Projects

A few projects provide additional features for Sandcastle. They work with or without the automation tools listed above.

Sandcastle Styles: Provides a rolled-up solution to various presentation style issues as well as additional resources that are useful to Sandcastle users.
Sandcastle Extensions: Provides a few Sandcastle build components and SHFB plug-ins that, for example, add the ability to add Help 2.x meta attributes and to have collection-level Help 2.x files generated automatically.
Drawbridge: Sandcastle build component that transforms Visual Studio class diagrams into images when it finds references in XML documentation, at build-time.

Related Downloads

There are a number of complimentary projects that are recommended to be used along with Sandcastle:

HTML Help Workshop

Provides Microsoft's Help 1.x compiler and GUI. Install this product if you want to build a distributable help package (.chm file) from the HTML topics generated by Sandcastle. Help 1.x files can be opened on any Windows system, stand-alone or included as part of the documented application.

Help 1.x enables context-sensitive help scenarios in managed applications and works with the .NET Framework's Help and HelpProvider classes.

Additional information about Help 1.x can be found on the Microsoft Help MVP Website - Help 1.x.

Visual Studio SDKs (2005, 2008)

Provides Microsoft's Help 2.x compiler and COM services. Install an SDK if you want to build a help collection (.HxS file) from the HTML topics generated by Sandcastle.

Help 2.x is useful for add-in, control and package developers that integrate their products into Visual Studio. An .HxS file can be merged with Visual Studio's help collections so that its documentation can be viewed in the Document Explorer, which is the external program that opens when you press F1 in Visual Studio.

Additional information about Help 2.x can be found on the Microsoft Help MVP Website - Help 2.x and in MSDN's Visual Studio SDK topics: Help Integration and Command-Line Programs.

AjaxDoc

Generates documentation for Atlas client script libraries. The XML documentation and reflection files that are produced can be used as input to Sandcastle and it will generate HTML topics that look like documentation for managed APIs.

XML Documentation

XML documentation can be generated automatically by managed compilers such as csc.exe (C#; use the /doc switch) and vbc.exe (VB.NET; use the /doc switch) from triple-slash /// comments in C# and triple-apostrophe ''' comments in VB.NET, respectively. Visual Studio can also be used to enable XML documentation output for your managed projects. For more information, see How to: Generate XML Documentation for a Project.

The compilers use a well-known schema to generate XML documentation files, which means that third-party tools and authors can write XML documentation as well. These files can then be passed to Sandcastle as input and it will include the data in the HTML topics that it generates.

Recommended Tags for Documentation Comments (C# Programming Guide)
http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx

Recommended XML Tags for Documentation Comments (Visual Basic)
http://msdn2.microsoft.com/en-us/library/ms172653.aspx

Dynicity LLC's XML Documentation Comments Guide
http://www.dynicity.com/Products/XMLDocComments.aspx

Conceptual Documentation Using Microsoft Assistance Markup Language (MAML)

Sandcastle can produce conceptual documentation from MAML, which is a set of XML schemas that define structured authoring elements for creating help topics. This allows an author to focus on the content instead of the formatting, which is applied later by a Sandcastle presentation style.

Sandcastle comes with a set of MAML schema files (.xsd), which can help you to author documentation using IntelliSense in Visual Studio's XML editor.

Conceptual output can be combined with auto-generated reference documentation to produce mixed user and reference documentation for compiled help or the web.

MAML References
There is no formal documentation for MAML available yet, however there are some articles on the web that provide an overview:

Sandcastle MAML Guide
http://www.codeplex.com/SandcastleStyles

Sandcastle Conceptual Help: Quick Start
http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

MAML Migration: The Next Step in the Evolution of Help Authoring
http://davesexton.com/blog/blogs/blog/archive/2008/05/24/maml-migration-the-next-step-in-the-evolution-of-help-authoring.aspx

Microsoft Assistance Markup Language. In Wikipedia, The Free Encyclopedia. [Background]
http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language

MAML - Microsoft Assistance Markup Language [Schema reference]
http://www.help-info.de/en/Help_Info_AP_Help/longhorn_maml_example.htm

Online Resources

Some useful online resources for Sandcastle include:

David Wright and Anand Raman on Sandcastle (dnrTV interview/training video)
http://www.dnrtv.com/default.aspx?showNum=84

Sandcastle Blog
http://blogs.msdn.com/Sandcastle

MSDN Forum: Developer Documentation and Help System
http://forums.msdn.microsoft.com/en-US/devdocs/threads/

Sandcastle Wiki (Note: This may eventually become obsolete in favor of the dedicated MSDN page below)
http://www.sandcastledocs.com

Sandcastle on MSDN
http://msdn2.microsoft.com/en-us/vstudio/bb608422.aspx

Developer Documentation and Help System Forum
http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

Creating Custom Build Components for Sandcastle, by Eric Woodruff
http://www.codeproject.com/csharp/SandcastleComponents.asp

Updated Wiki: Sandcastle Help

davedev — Wed, 02 Jul 2008 18:42:39 GMT

Sandcastle Help

Introduction
Key Points

General Information
Usage
Output
Common Issues

Build Scripts
Community Projects

Open Source GUIs for Sandcastle
Supplementary Community Projects

Related Downloads
Xml Documentation
Conceptual Documentation Using MAML
Online Resources

Introduction

This document provides important information and links to various online resources for learning about Microsoft Sandcastle.

Key Points

Here are some key points that you should know about Sandcastle before you get started:

General Information

Sandcastle is currently released on CodePlex (http://www.codeplex.com/Sandcastle).
Sandcastle is also bundled as an older community technology preview (CTP) with the Visual Studio 2005 and 2008 SDKs.
Sandcastle is based on Microsoft's internal tools that are used to build documentation for Visual Studio and the Microsoft .NET Framework.
Sandcastle is not open source.
In the past, a new CTP version of Sandcastle was released approximately every 1 to 3 months. This pattern is expected to continue.

Usage

Sandcastle is not a single executable program but is actually a set of programs and XSL transformations that must be used together.
Sandcastle is extremely flexible and offers many configurable features.
Sandcastle's build process can change depending upon the desired output, format and presentation style, so there isn't one universal process that can meet everyone's needs.
Sandcastle can be used in various scripts such as batch files, MSBuild and PowerShell. (See Build Scripts below for more information.)
Sandcastle provides an example graphical user interface (GUI) that automates an MSBuild script, but it does not provide Visual Studio integration and many of the desirable features that users have come to expect from help authoring tools (HATs); although, the open-source community does. (See Open Source GUIs for Sandcastle below for more information).

Output

Sandcastle supports different presentation styles, including one that looks like the documentation for Visual Studio and the Microsoft .NET Framework.
Sandcastle produces XML-based HTML topic files using two different processes, which can be combined together to produce mixed documentation:

Conceptual documentation (e.g., custom topics, walk-throughs, how tos, troubleshooting) is built from Microsoft Assistance Markup Language (MAML). (See Conceptual Documentation Using MAML below for more information.)
Auto-generated reference documentation is built for managed and unmanaged application programming interfaces (APIs).

Reflection information for managed assemblies can be generated automatically by Sandcastle's MRefBuilder.exe program.
Reflection information for unmanaged libraries must be generated by a third-party tool. (AjaxDoc is one example.)
Sandcastle can optionally integrate XML documentation from code comments or external tools into auto-generated topics. (See Xml Documentation below for more information.)
Sandcastle will pass through many common HTML tags in XML documentation (code comments), such as <p>, <img>, <strong>, etc.

Sandcastle itself does not build compiled help (e.g., HTML Help 1.x, 2.x) but the installed build scripts enable this scenario out-of-the-box with some additional software. (See Related Downloads below for more information and links to downloads.)

Common Issues

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
           assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
  <index name="comments" value="/doc/members/member"
         key="@name" cache="100">
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727"
          recurse="false" files="*.xml" />
 
    <data files="Comments\*.xml" />  <!-- This line was modified -->
 
  </index>
  <copy name="comments" source="*" target="/document/comments" />
<components>

Build Scripts

Graphical User Interface (GUI): Examples\generic\SandcastleGui.exe
MSBuild project: Examples\sandcastle\build.proj
Command-line batch script: Examples\sandcastle\build_Sandcastle.bat
Windows PowerShell script: ProductionTools\scbuild.ps1

Community Projects

Several products have been developed by the user community to improve Sandcastle's usability and to enhance its feature set.

Open Source GUIs for Sandcastle

The following open source projects provide GUIs for automating Sandcastle. They allow you to easily configure settings and build documentation with various output types:

DocProject: Visual Studio 2005/2008 integration using MSBuild project templates, an Add-In and GUIs.
Sandcastle Help File Builder: A popular NDoc-style GUI and console-mode application with custom build components.
Sandcastle GUI: Another popular GUI for Sandcastle.

Supplementary Community Projects

A few projects provide additional features for Sandcastle. They work with or without the automation tools listed above.

Sandcastle Styles: Provides a rolled-up solution to various presentation style issues as well as additional resources that are useful to Sandcastle users.
Sandcastle Extensions: Provides a few Sandcastle build components and SHFB plug-ins that, for example, add the ability to add Help 2.x meta attributes and to have collection-level Help 2.x files generated automatically.
Drawbridge: Sandcastle build component that transforms Visual Studio class diagrams into images when it finds references in XML documentation, at build-time.

Related Downloads

There are a number of complimentary projects that are recommended to be used along with Sandcastle:

HTML Help Workshop

Visual Studio SDKs (2005, 2008)

AjaxDoc

XML Documentation

Conceptual Documentation Using Microsoft Assistance Markup Language (MAML)

Online Resources

New Post: Code Example: Reference source code file in project?

davedev — Wed, 02 Jul 2008 15:19:59 GMT

Hi Mike,

You have to add the SyntaxComponents assembly using the <add /> element as in my example, not the components assembly :)

This is because one of the components (I assume the Code Block Component) references the SyntaxComponents assembly, but since SyntaxComponents is not in the GAC it cannot be resolved automatically by the Framework from within Visual Studio's process (where the DocProject add-in lives). By adding SyntaxComponents as a dependency, DocProject will handle assembly resolution automatically whenever the Framework needs to load the assembly. Which, in VS 2008, just so happens to be immediately when the build components assembly is inspected for types since delayed-loading is now apparently an unsupported scenario in VS 2008.

https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=340664
http://davesexton.com/blog/blogs/blog/archive/2007/11/16/docproject-2008-beta-2-assemblyresolve-showstopper.aspx

- Dave

New Post: Code Example: Reference source code file in project?

mdbell — Wed, 02 Jul 2008 14:26:28 GMT

Thanks.

I downloaded the Sandcastle Standalone Build Components, unblocked them (Vista!, I've learned my lesson there) and copied the folder SBComp_v1700 to the Sandcastle ProductionTools folder.

Then I added the following line to the relevant place in C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config (a little different because the DLL is not the same):

<add name="CustomBuildComponents" assembly="%DXROOT%\ProductionTools\SBComp_v1700\SandcastleBuilder.Components.dll" />

I opened my solution. In the DocProject properties I opened the ellipsis for Help 1.x conceptual build component stack.
I clicked the Add Build Component button.
The available build components does not list anything from SandcastleBuilder.Components.dll
When I click the Browser... button and find SandcastleBuilder.Components.dll I get the error:

"One or more of the selected assemblies could not be inspected due to the following error: Unable to load one or more of the requested types. Retrieve the LoaderExceptions property for more information".

Any ideas?

// Mike

New Post: Code Example: Reference source code file in project?

davedev — Wed, 02 Jul 2008 13:19:12 GMT

Hi,

See the following discussion about the Code Block Component. I think it also works for conceptual documentation but I don't know for sure.

http://www.codeplex.com/DocProject/Thread/View.aspx?ThreadId=28446

Note that if you're using Visual Studio 2008 then you must add a line to DocProject's configuration file for the Code Block Component to work correctly:

Open DocProject's configuration file; commonly, C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config (do not confuse this file with DocProject.exe.config).
Add the following element as a child of the configuration\addin\dependencies element.

<add name="SyntaxComponents" assembly="%DXROOT%\ProductionTools\SyntaxComponents.dll" />

- Dave

New Post: Code Example: Reference source code file in project?

mdbell — Wed, 02 Jul 2008 10:06:25 GMT

I have a C# file in my DocProject that contains some sample code, nicely decorated with comments and compilable.

I am wondering if there is a way of including the content of that file in a <codeExample> section, for example <code language="c#" addres="???"> rather than copy the content to the aml file and mangle the < and > characters into HTML.

Updated Wiki: Wikimap

davedev — Tue, 01 Jul 2008 00:30:58 GMT

Wikimap

Home Page

About DocProject
Overview of DocProject as an open source project and a list of its features.
Latest Release Notes
Please read this document carefully before attempting to install DocProject.
Sandcastle Help
Provides important notes and links to various online resources for learning more about Microsoft's Sandcastle tools.

Sandcastle and Proxy Servers
Information about using proxy server configurations with Sandcastle.

Sandcastle Build Component Templates
Visual Studio Item Templates for creating custom Sandcastle build components that can take advantage of editor support in automation tools such as DocProject.
ResolveExternalLinksComponent
Provides documentation for ResolveExternalLinksComponent, which is a Sandcastle build component that extends <see> tags by allowing IDs to be specified instead of URLs.
DocProject External UI
Provides support for configuring and building DocProjects and DocSites outside of the Visual Studio IDE (useful for Visual Studio Express users).
DocProject Components
Overview of DocProject's two major components: Visual Studio Project Templates and a Visual Studio Add-In.
DocProject Templates
DocProject templates are used to create Visual Studio projects that build compiled help for their project references and external sources.

DocSite Templates
DocSite templates are DocProject templates that generate Visual Studio Web Application projects.

Build Process
Information regarding the build process, steps and build types of DocProjects and DocSites.
Sandcastle Deployment Plugin
The Sandcastle/Deployment plug-in extends the Sandcastle build engine in DocProject by adding deployment features.
How To...
Guidance for performing some common tasks associated with DocProject.

Installation and Uninstallation

Configuration

Using DocProject

Sandcastle Features in DocProject

Usage Tutorials

Extensibility Tutorials

Updated Wiki: How To...

davedev — Tue, 01 Jul 2008 00:30:25 GMT

How To...

Here you'll find guidance for performing common tasks related to DocProject and Sandcastle. (See below for Tutorials.)

Installation and Uninstallation

Configuration

Using DocProject

Sandcastle Features in DocProject

Tutorials

Here you'll find step-by-step instructions for performing some common and advanced tasks related to DocProject.