如何制作电子文档CHM(How to gernerate chm from assembly)

 

2011-09-04 01:12:09|  分类：默认分类 |  标签：chm  assembly  build  generate  |字号大中小 订阅

目的
 大多数情况下，开发人员编写的代码最后都会生成程序集Assembly。 当其他开发人员（本公司或其他公司）调用程序集时，都会花费几天或数周的时间来熟悉整个程序集(或者称之为框架)，当然花费时间的长短很大程度上取决于程 序的代码量，难易程度，科技含量，开发者的水平。但无论是哪一种，都要花费一定的学习时间才能上手，怎样才能提高学习的效率，快速上手， 熟悉API呢？ 制作程序集的电子文档(chm)很关键。 本文就制作的过程做一个描述。

前提条件
 工具介绍

Sandcastle -
Sandcastle is a documentation compiler for Managed class library that generates Microsoft-style Help topics, both conceptual and API reference. It creates API reference topics by combining the XML documentation comments (/// in C# or ' in VB) that are embedded in your source code with the syntax and structure of the types, which it acquires from reflecting against the associated .NET Framework assembly. Skeletal topics are created by using reflection on your project assembly (.dll) file. Additional content, such as remarks and parameter descriptions, is derived from text in the /// comments in your c# source code or ' comments in your VB source code. Conceptual topics are created by converting XML documents that you author.
说明白点，Sandcastle主要是对程序集里的comments的进行抽取，生成对应的html或chm。 如果无法生成chm时，可参考以下工具 HTML Help Workshop.

下载地址 ： http://sandcastle.codeplex.com/wikipage?title=Introduction&referringTitle=Home


Microsoft HTML Help Workshop (GUI)
包含2个重要工具，一个是HTML Help Image Editor, 一个是HTML Help Workshop生成器,GUI操作的。

下载地址 ： http://msdn.microsoft.com/en-us/library/ms669985

hhc.exe (alternative)
默认情况下，hhc位于C:\Program Files (x86)\HTML Help Workshop目录中.(win7环境中)。这是一个备用的控制台工具，可以通过命令行来进行启动，完成build操作。
 
预览

 

详细过程
1. 使用vs2010生成程序集，并生成xml documentation文件
用vs2010打开项目工程proj或解决方案sln文件,右键点击项目->选择属性->选择Build->勾选上XML documentation file并填上xml的文件名，如下所示 

编译后会生成2个文件，一个是程序集，一个是xml文件，里面包含了所有的comments,如下所示

 
     
2.使用Sandcastle生成html文件以及构建chm必要的hhp文件。
找到Sandcastle的安装路径，在Examples\Generic目录中双击SandcastleGui.exe,打开GUI操作界面，如下所示

在Assemblies中添加需要制作完chm的程序集，在Comments添加xml documentation file，在Dependent Assemblies添加上前面程序集依赖的其他程序集（有则添加，无则不用理会），在Options的Name中填写名字（生成的chm会用此名），具体如下所示

生成以下文件
html 文件 chw文件 hhc文件 hhk文件 hhp文件(生成chm直接引用的文件)

3.使用HTML help Workshop生成chm。
如果第2项在生成chm的时候，遇到未找到HTML help workshop或hhc.exe问题，可以先自行下载HTML help workshop安装包或找到hhc.exe通过命令行方式来生成chm. 具体如下所示

通过命令行方式来生成chm，如下所示

新建一批处理文件bat,然后输入以下内容

rem

rem build itextsharp chm

rem

"C:\Program Files (x86)\HTML Help Workshop\hhc.exe"  "D:\Program Files (x86)\Sandcastle\\Examples\iTextSharp_chm\vs2005\chm\iTextSharp_chm.hhp"

pause

然后双击bat文件，即可。

参考资料
http://sandcastle.codeplex.com/wikipage?title=Introduction&referringTitle=Home
http://msdn.microsoft.com/en-us/library/ms669985
http://social.msdn.microsoft.com/Forums/pl-PL/devdocs/thread/664ea702-259d-4532-aaa0-a926c63b27bb

版权申明

作者：Charly Liu
出处：http://winlcq123.blog.163.com/ 
本文版权归作者和网易博客共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利