Sandcastle Generating Help documents

Http://www.cnblogs.com/net515/p/3311584.html

Sandcastle Help Document Builder usage Introduction first, the introduction of software      sandcastle is a document compiler for managing class libraries, a tool for compiling publishing component (Assembly) information, which, through reflection and XSLT technology,　　You can get a complete help document from the DLL file and its XML Comments (command-line compile-time plus/doc parameter or VS2005 set project properties), in either HTML or CHM or even any custom format. Sandcastle is used in combination with. net framework 2.0 and. Net compact framework.　　Sandcastle supports localization and provides a basic command-line compiler interface and a Visual studio plugin. Sandcastle The CCP has three components: Mrefbuilder, Build assembler and XslTransform. These tools use the output generated when compiling assembly code, including DLL files and XML comment files.   Mrefbuilder reflects the assembly code of a project and generates an output file. Mrefbuilder is a command-line tool that is installed with Sandcastle. The output file it generates is converted to a file called Reflection.xml through the XslTransform command-line tool. The Reflection.xml file contains all the document data, but does not provide display details.   Mrefbuilder After the completion of the work, immediately by the Build assembler handle. 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. The Html help compiler then uses these HTML files to generate the final result.   The tool does not limit you to working with a compilation at a time. If you need to work with several assembly codes, you must drill down into the sandcastle configuration file.　　It is an XML file that contains the steps required to create a Help file topic. The output generated by Sandcastle has the following characteristics: ø          an interface similar to the MSDN layout.  ø          automatically generates index entries, content item tables, topic blocks, and page layouts to improve consistency and familiarity. ø          automatically generates a syntax claim section.  Ø          automatically generates inheritance tables.  Ø          code coloring.  Ø          offers a variety of styles and language choices that end users can choose from their favorite forms.  Ø          output is displayed in HTML and CSS, and Microsoft is committed to offering more options in the future. second, the use of softwareThe software is used in roughly the following 5 ways: (1) Use Sandcastle original command line (2) Sandcastle help File Builder (3) Sandcastlegui (4) Sandcastle CHM compilation Bat script and Configuration Utility (5) Docproject This article takes the form (2) as an example to introduce the use of sandcastle 1. Specification for generating document code annotations:In the source code file, annotations with canonical formatting can be used to instruct the tool Sandcastle.msi to generate XML based on these annotations and the source code elements that follow them. Annotations that use this type of syntax are called document annotations (documentation comment). These comments must be followed immediately by a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method). The XML generation tool is called the document Generator (documentation generator). The output produced by the document generator is referred to as a document file (documentation files).　　Document files can be used as input to the document viewer (documentation Viewer), and document viewer Sandcastle is a tool for generating a visual display of type information and its associated documents. The new code comment specification requires the use of three slashes (/////) to begin commenting, which must be followed immediately by the user-defined type (such as a class, delegate, or interface) or member (such as a field, event, property, or method) that they annotate. It is necessary to use valid XML tags for annotation commentary. Some of the marks are as follows: 2. Download and install ---sandcastle   http://sandcastle.codeplex.com/  //Raw   ---shfb (Sandcastle Help File Builder)   http://shfb.codeplex.com/ //articles we need to use.  ① If you have previously installed other versions, please uninstall and reload them first.  ② download completed after decompression, I use the shfbguidedinstaller_1970 version, get the following     open SandcastleInstaller.exe into the installation interface     Installation is quite simple, in a connected environment, the required components are automatically prompted to download the installation. During the test, except for Maml Schema IntelliSense and Maml Snippet files chose to skip without installing, the other all based on the prompts installed. (Because I don't understand what those two things do).   After the installation is complete, you can find it in the Start menu, open the program, as follows   a. After opening the software, first create a new solution, be careful not to build the desktop and other locations, or generate error. B. After the solution is completed, right-click on documentation Sources on the project Explorer to add the DLL file that needs to generate the help document. The DLL file that I added in Figure ① to generate the Help document C. The bottom content layout1.content is the style of the resulting help document, which can be completely removed. D. Select the format in which you want to generate the Help document, ②, where I want to generate the HTML-formatted help document. E. Other settings by default, you will be introduced below. F. Click ③ to start the build,  g. When the build is complete, you will see a prompt:Build completed successfully at 09-09-2013 11:47 pm. Total time:00:01:11.3906 You can see the Help folder in the Sandcastle solution directory, which is the generated helper file. H. If you cannot compile a CHM document or generate a CHM-times error, you will need to install HTML Help Workshop (the Hhc.exe file that you need to use) 3. Integration into Visual StudioA. Go back to the Sandcastle installer directory, open the Installresources folder, see the following three files double click the bottom VSIX file, the reaction will pop up the following error, that is, the installation was successful: B. Now add the project to the solution, as follows c. Select Documentation-->sandcastle Help File Builder project--> OK d. Double-click Project Properties You can set property properties for an item the main properties of personalization are: 1. Generate property settings, such as what type of document you need to generate (optional CHM, site site, etc.) 2. Document content property settings, such as a description of the namespace. (Namespaces are not annotated in C # code, so you can set them here, or you can create a new class in your project NamespaceDoc.cs whose code is:

1NamespaceTestforhelp2  {3 ///<summary>4 these is the namespace comments for New <c>< Span style= "color: #008000;" >testforhelp</c>5 ///</summary>6  [System.Runtime.CompilerServices.CompilerGeneratedAttribute ()]7  Classnamespacedoc8 9}            

3. Document file property settings: such as header, footer, copyright information. E. Similarly, right-click on documentation Sources to add a DLL file that needs to generate a Help document, you can add more than one f at a time. Right-click on the project name (e.g. Documentationhelp), add-new item to specify project template G. Once all settings are complete, build the project to get the help document you want, and also save it under your projects under the helps folder. H. Again, if you cannot compile a CHM document or generate a CHM-times error, you will need to install HTML Help Workshop (the Hhc.exe file that you need to use)
Reference: 1. Using the Sandcastle Help document generation process 2. Use Sandcastle to generate help documents 3. Use Sandcastle to generate the CHM Help document (using Sandcastle original command line) 4. The software's help documentation is very comprehensive, But it's all in English.

Sandcastle Generating Help documents