Sandcastle Help File Builder

Recently, I have worked with other departments to provide them with an external service. Since it is provided to others, I certainly need to tell others how to use your service, this is what we often call technical documents. There are many ways to transmit technical documents between groups. Here I know about the following types:

1. Deliver technical documents orallyThat is, if there is no substantive documentation, just give a verbal explanation. This situation is limited to a development team that is very convenient to communicate, such as sitting in an office room.

Second, record the technical points used in the form of textWhat is the use of this method, what is the property, and so on? This method is undoubtedly the most clear expression. In a separate document, you can even use graphs to teach users, however, the disadvantage is that the maintenance is quite troublesome and time-consuming. If the implementation of the service changes a lot one day, it will be very troublesome to update this document.

Third: use tools and. Net annotations to automatically generate help filesHere is the sandcastle Help File builder mentioned in this article, which is hereinafter referred to as shfb. It is a visualization tool of sandcastle. users do not need to remember a large number of commands to compile documents. It can finally generate a CHM file. The content style can be msdn, which makes it easy to use.

 

Implement the shfb software environment:
First, you need to install sandcastle. You can search and download the latest version.
In fact: it is the CHM File production software HTML Help Workshop. This latest version is 1.3, and some are not updated. The two software must be installed in the default path; otherwise, these two parameters must be set in shfb.

 

Steps:
First, modify the property of the project for which the help project is generated, right-click the project, and select Properties to generate. In the output box below, an XML file generation option is checked. The file saves comments on all classes, methods, and properties in the project.
2. Start shfb and create a new project. The name can be specified at will. The following describes several important attribute settings:

1: documentation sources, which is a project that generates detailed annotations. If the outermost project references other projects and we want to see all referenced classes, we need to add all referenced projects. Otherwise, when you click the outer class, there is no link on the referenced class, that is, we cannot see the content of the referenced class.
2: References: Set the dependencies of some projects.
3: frameworkversion: select the corresponding framework version. The default value of shfb in the latest version is. Net 3.5.
4: helpfileformat: select the format of the document to be generated. The format selected here must be set in the corresponding area below. For different formats, you also need to install different compilation tools helpe1x (CHM). Microsoft HTML Help needs to be installed, and hxcomp needs to be installed for helper2x (HXS.
5: namespacesummaries: select the namespace to be generated and click open window to select.

6: lanugages: language. If the document contains Chinese characters, you are advised to select Chinese.
7: copyrighthref: copyright link, such as http://www.xxx.com/
8: copyrighttext: copyright text, owned by XX Company
9: helptitle: document title
10: htmlhelpname: name of the file generated
11: presentationstyle: supports formats such as VS 2005 and prototype. Select one based on your needs.
12: outputpath: The generated path, that is, the last CHM File storage location. Of course, there are some other files besides CHM.
13: htmlhelp1xcompilerpath: You can customize the installation path of HTML Help.
14: sandcastlepath: You can customize the installation path of sandcastel.

At this point, we can click the "buile the Help File" button in the software window to generate the document as expected. If there are no special circumstances, there will be no errors during the running, we will successfully find the CHM file in the output directory, but in some cases, you should pay attention to the following:

1. When documentation sources is added, the path cannot contain the words. H. For example, the path. Hotel. Host \ bin is invalid. The HHC software reports an error.

Second, references cannot contain duplicates.

How can I write comments normally to generate detailed and available help documents?

1: Class annotation. It is generally divided into summary and remarks.

Code

///   <Summary>
/// SMS upstream Service
///   </Summary>
///   <Remarks>
/// 2010.07.09: Create. Min. Jiang <Br/>
/// 2010.07.09: develop SMS upstream Service <Br/>  
///   </Remarks>
[Servicebehavior (instancecontextmode = Instancecontextmode. percall,
Concurrencymode = Concurrencymode. Multiple,
Includeexceptiondetailinfaults =   True )]
Public   Class Publish commentwcf: iworkflow commentwcf

 

2: Comment the method. In addition to the Summary and remarks in the class, you can add example and add the instance to the code label.CodeAnd so on.

Code

///   <Summary>
/// The Platform invites users to comment on their mobile phones
///   </Summary>
///   <Param name = "request"> User comment </Param>
///   <Returns> Comment handling result </Returns>
///   <Remarks>
/// Sends the comment to the user's mobile phone.
///   </Remarks>
///   <Example>
/// <Code>
/// Required commentwcfclient target = new required commentwcfclient ();
/// Elong. Hotel. serviceagent. Test. Comment commentwcf. Comment commentrequestinfo request = NULL;
/// Request = new elong. Hotel. serviceagent. Test. Comment commentwcf. Comment commentrequestinfo ();
/// Request. Required orderlast4 = "3716 ";
/// Request. Mobile = "********";
/// Request. recommentcontent = "AAA ";
/// Elong. Hotel. serviceagent. Test. Publish commentwcf. responsebaseinfo actual;
/// Actual = target. smgandcomment (request );
///   </Code>
///   </Example>
Public Responsebaseinfo smgandcomment (Response commentrequestinfo request)

3: Comment the attribute. This is the simplest. Generally, there is a summary block, and there is a value block, which can be described for the default value.

Summary:Sandcastle Help File builder can work very well with vs to produce msdn-style help documents, which effectively saves technical documents for projects and reduces communication costs.

 

Author: Jiang min
Source: http://www.cnblogs.com/aspnet2008/