. NET XML Comments (i) Creating help documents

I. Summary

The first article in this series describes the. NET FOR XML annotations, this article explains how to use XML annotations to generate the same Help files as MSDN. Main Introduction NDoc successor: SandCastle.

Two. Background

To generate a Help file, many people will think of NDoc. In fact, VS2003 does not use NDoc as well as the ability to generate Web documents. Unfortunately, this feature has been canceled in Visual studio after upgrading to VS2005 and VS2008. Even more unfortunate is ndoc this project due to funds and other issues, the author Kevin in July 2006 announced that no longer into the NDoc open source project development, NDoc stay in the historical version of 1.3, unable to fully support. NET 2.0, will gradually fade out of people's horizons.

I was using VS2003 last year. So the build Help document uses its own build Web Document feature, which automatically generates HTML-formatted help documents based on comments. Today our company has fully upgraded to VS2008 and Framework3.5, So after some toss found that can not find the previous function, and NDoc also do not support Framework2.0.

After a few twists and turns, I found Sandcastle, a software developed by Microsoft. Thank you, Microsoft Forum Moderator "Zhou Xuefeng" for my guidance to tell me the existence of this software.

Prior to the release of VS2005, a tool was developed within MS to generate help documents. This is the predecessor of Sandcastle. But it took more than 10 hours to compile the document at the time, making the tool less usable. Later, as the version continues to optimize, it takes about 3 minutes (minutes, depending on the size of the generated document) to generate a help document.

Three. Sandcastle Introduction

The Help files in the previous article were generated using sandcastle, such as the following:

Sandcastle is a Microsoft-released tool that creates API documentation in the form of MSDN by reflecting the source code in the assembly and adding XML annotations in the code. The source code for this tool can be obtained under Microsoft Public License Agreement (License) in CodePlex. SandCastle Main features are:

• Compatible with signed or unsigned notes
• Support for the paradigm and the. NET 2.0 Framework
• Support for all. NET language
• Support for. NET Compact Framework Projects
• Simple compile interface and Visual Studio plug-in

Four. How Sandcastle works

Download the source code for sandcastle from CodePlex, and you will find the following items when you open it:

The relationship between these items can be expressed in the following:

The role of the parts:

• There are three main components in Sandcastle: Mrefbuilder, Build Assembler, and XslTransform.
• HTML Help 1.x compiler (Hhc.exe) or Microsoft Help 2.0 compiler (Hxcomp.exe) is used to generate. chm or. hxs files
• The Help Viewer is used to view the assistance files.

Mrefbuilder and XslTransform

Mrefbuilder generating output files from an assembly using CCI

XslTransform generates Reflection.xml documents and manifest files using the above output files. Reflection.xml contains all data with no presentation elements.

Buildassembler

Build assembler can be started by the command-line tool Buildassembler. It uses data generated by Mrefbuilder (reflection.xml) and any code annotations (saved in a separate XML file) to generate logically grouped HTML files.

HTML Help Compiler (1.x, 2.0) then uses these HTML files to generate the final result.

In addition to the three components of the core described above, there are a number of tools for generating final files. For example, HTML Help complier This role is done using the HTML Help Workshop tool. HTML Help Workshop is not in the Sandcastle project , you need to download it separately. To generate a document in the final. chm format, you must install HTML Help Workshop.

We note that there is a chmbuilder in the source code that is used to generate a. HHC class of files that are available for use by HTML Help Workshop, which are metadata for. chm format files. HTML helps The role of workshop is to generate final documents based on these files.

Five. Get started quickly sandcastle

This article only from my knowledge, explain how to quickly and easily use Sandcastle. The method may be cumbersome. To use it in a duck's eye it now seems necessary to use a third-party-developed sandcastle Helper. I'll take the time to study in later articles in this series.

(1) Preparing the software

First we need to prepare the following software:

SandCastle,: http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx Description: The connection above is linked to CodePlex The latest release version of the Sandcastle project on the page. There are two ways to download them:

Please download the Sandcastle.msi file, which contains some of the tools we will use such as GUI. and the following source code is not included in the zip, It can be seen from the size as well. Users who know how to use SVN and TFS can also get the latest version of the Sandcastle in development from the source code server, and I get the version of it on SVN, which also includes all the content and tools.

HTML help Workshop,: http://www.microsoft.com/downloads/details.aspx?familyid=00535334- c8a6-452f-9aa0-d597d16580cc&displaylang=en

(2) Preparing project documents

An XML file that prepares the program's DLL files and comments. Two files for example in this article: XmlCommentClassDemo.dll and Xmlcommentclassdemo.xml

Note If our project is associated with more than one DLL, you will need to prepare the DLL and comment XML files for the related project. Otherwise, you will not be able to click the related class in the Help file. (If you add a project DLL and XML file that contains a class, this class can be clicked in the CHM file and then jumped to the description page of the class.)

(3) using GUI to generate Help file meta data

After installing Sandcastle, GUI tools are found in their generic directory: SandcastleGui.exe, run Interface:

As shown, after you enter "Xmlcommentdemo" in name, click Build, and you will first be prompted to save a sproj file.

The default is to create a folder: C:\Program Files\sandcastle\\examples\xmlcommentdemo

After sandcastle we have generated the CHM file metadata file, the path is guaranteed to exist:

C:\Program the Files\sandcastle\examples\xmlcommentdemo\vs2005\chm\ folder.

(4) Using HTML Help Workshop to generate CHM files

There are three files in the C:\Program files\sandcastle\examples\xmlcommentdemo\vs2005\chm\ folder:

Xmlcommentdemo.hhc

Xmlcommentdemo.hhk

Xmlcommentdemo.hhp

You can open the XMLCOMMENTDEMO.HHP file by running HTML Help Workshop. Once you have opened the file, click "File", "Compile ..." to eject the interface as follows:

When you click Compile, the. chm file is generated in the. hhp directory, as shown in the following:

Xmlcommentdemo.chm is the final document.

Five. Summary

The introduction of this article will be used. NET annotations to XML format files and program DLL files that generate MSDN-like documents. For comments in the help documentation, see the first article in this series.

As a result of limited research I can only use sandcastle at present, follow-up articles will be in-depth study of the use of sandcastle. I hope we can discuss together, study together, progress together.

Six. Related Resources

Microsoft Sandcastle Blog: http://blogs.msdn.com/sandcastle/default.aspx

Sandcastle Project: Http://www.codeplex.com/Sandcastle

. NET XML Comments (i) Creating help documents