【转】Sandcastle----强大的C#文档生成工具

Sandcastle----强大的C#文档生成工具

 最近客户索要产品的二次开发类库文档,由于开发过程中并没有考虑过此类文档,而且项目规范比较，持续时间比较长，经手人比较多，还真是麻烦,如果人工制作文档需要是一个比较大的工程.还好有这个文档生成工具,能够根据项目生成文档,而且格式看起来确实很专业.
     Sandcastle是微软官方的文档生成工具，NDoc开发停止后，这个貌似也是唯一的一个这方面的工具。它从dll文件及其xml注释文件能够生成完整的帮助文档，支持多种生成格式(Helpe1x:chm, Helper2x:Hxs, Website,HelperView),结合新发布的Sandcastle Help File Builder可视化工具，整个生成过程十分简单，而且SHFB工具看起来很强大，不仅能够直接配置生成文档的各个属性，而且还支持很灵活的扩展设置，为我们提供完美的.NET类库文档成为一个可能。
      来一步一步的看下整个生成过程:

     1.从这里下载最新的Sandcastle后安装.
     2.从这里下载今年才发布的Sandcastle Help File Builder.
     3.安装完成后直接新建项目，主窗口会直接打开项目属性，这里就是对生成文档的主要配置区域。我们先添加需要生成文档的源。右击项目中的Documentation Sources可以添加多种文件类型（sln,proj,xml,dll,exe) 
     4.对主要的属性进行设置.
       FrameworkVersion:  选择对应的Framework版本
       HelpFileFormat :  选择需要生成的文档的格式. 注意这里选定的格式要在下面对应的地方进行设置.
                              注意对于不同的格式还需要安装不同的编译工具 Helpe1x(chm)需要安装Microsoft HTML Help,Helper2x(Hxs)需要安装 Hxcomp.
      NamespaceSummaries:  选择需要生成的命名空间，直接点击开窗选择。这可强大多了，之前用命令行或者其它工具都是要手动输入。
      Lanugages ：语言一定要选择中文，这会使一些文档里的一些文字自动生成中文
      CopyrightHref:版权链接
      CopyrightText: 版权文字
      HelpTitle: 文档标题
      HtmlHelpName:文档生成文件名称
      PresentationStyle: 这里现在支持vs 2005,Prototype等格式 ，根据自己需要选择
      OutputPath:生成路径
      Show Missing Tags:下面的一些设置根据需要在最终版生成时设置成True,不然会在文档中出现红色的提示.
    设置完成的界面如下:
       未命名

      5.点击上面的生成菜单或者按钮，就可以直接打开生成过程界面，在这里可以直接查看生成过程中的一些提示和错误.生成完成后，一个和MSDN风格一致的文档就出来了:
       未命名 
    
     6. 而且支持在文档中插入图片，插入代码等功能。
     7.代码规范是最根本的前提，一定要在代码中提加足够的注释。

资源: 
          Sandcastle Help File Builder：    http://shfb.codeplex.com/
          SandcastleGUI：http://www.inchl.nl/SandcastleGUI/ 之前一直使用的另外一个Sandcastle生成工具
          用Sandcastle和Help Integration Wizard把文档集成到Visual Studio   
           http://www.cnblogs.com/fox23/archive/2008/09/09/using-sandcastle-integrated-help-documents-into-visual-studio.html

 

 

作者：孤独侠客（似水流年）
出处：http://lonely7345.cnblogs.com/
本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。

孤独侠客
关注 - 14
粉丝 - 31
荣誉：微软社区精英
7
0
(请您对文章做出评价)
« 上一篇：Sculpture ----基于MDD的集成开发平台
» 下一篇：Visual Studio DSL 入门 1
posted @ 2010-01-13 23:19 孤独侠客 阅读(2703) 评论(13)  编辑 收藏 所属分类: Open Source

 

  回复  引用  查看    
#1楼2010-01-14 08:19 | 剧终      
谢谢分享
不过微软还有个内部工具叫DocGen的，不知道外面有没有
  回复  引用  查看    
#2楼2010-01-14 08:32 | 景坤      
很好。顶
  回复  引用  查看    
#3楼2010-01-14 08:45 | 李锡远      
这是个好东西
  回复  引用  查看    
#4楼2010-01-14 09:27 | 王小二      
收藏喽。
  回复  引用  查看    
#5楼2010-01-14 09:51 | wbkt2t      
生成的一直提示
[Missing <summary> documentation for "****"]错误
应该是没有注释导致，但是我已给这个class写上注释了



view source
print?
1 /// <summary>
2         /// 增加记录
3         /// </summary>
4         /// <param name="model">Feature mode</param>
5         /// <returns>整数</returns>

但还是不行，还是我哪里写错了，望lz指教
  回复  引用  查看    
#6楼2010-01-14 10:36 | Tony Zhou      
Sandcastle貌似终于有UI了阿，之前只能command操作痛苦死了
  回复  引用  查看    
#7楼2010-01-14 11:08 | 干拔三分      
引用wbkt2t：
生成的一直提示
[Missing <summary> documentation for "****"]错误
应该是没有注释导致，但是我已给这个class写上注释了



view source
print?
1 /// <summary>
2         /// 增加记录
3         /// </summary>
4         /// <param name="model">Feature mode</param>
5         /// <returns>整数</returns>

但还是不行，还是我哪里写错了，望lz指教

我也是这样
  回复  引用  查看    
#8楼[楼主]2010-01-14 11:27 | 孤独侠客      
@干拔三分
引用干拔三分：
引用wbkt2t：
生成的一直提示
[Missing <summary> documentation for "****"]错误
应该是没有注释导致，但是我已给这个class写上注释了



view source
print?
1 /// <summary>
2         /// 增加记录
3         /// </summary>
4         /// <param name="model">Feature mode</param>
5         /// <returns>整数</returns>

但还是不行，还是我哪里写错了，望lz指教

我也是这样


在生成项目的时候在项目的属性里面有没有选中生成Xml文档
  回复  引用  查看    
#9楼2010-01-14 12:18 | 干拔三分      
我选中了
但是很奇怪的
我新建一个测试项目就没问题
在我原来的项目上生成就不行
  回复  引用  查看    
#10楼[楼主]2010-01-14 13:00 | 孤独侠客      
@干拔三分
再查一下文件的位置对不对
  回复  引用  查看    
#11楼2010-01-29 09:58 | C雷      
学习了...赞一个!
  回复  引用  查看    
#12楼2010-02-28 15:46 | 咸鱼翻身      
SandcastleGUI 有点问题
配置好后点生成按钮程序就死了
  回复  引用  查看    
#13楼2010-05-04 09:19 | 小齐      
No APIs found to document. See error topic in help file for details.
请问提示这个错误怎么处理
posted @ 2010-05-28 22:10  上善若水-water  Views(1317)  Comments(0)    收藏  举报