文档API生成神器SandCastle使用心得
一、功能描述
关于Sandcastle网上的参考资料相对较少,Google出来很多资料都是全英文的,相对于我这种英语渣渣看起来还是很费劲的。
言简意赅,Sandcastle主要功能是能够将C#类生成类似MSDN风格帮助文档的工具,支持本地化,并提供一个基本的命令行编译器界面和一个Visual Studio插件。
优点:
1.生成简单,工作量小,几分钟之内就能完成一个项目的api文档制作。
2.自动生成索引项、内容项目表、主题块和页面布局,提高一致性和熟悉程度。
3.代码高亮,易读性强
4.生成api界面美观。
缺点:
只支持visual studio,意思是只支持微软旗下产品。
二、下载与安装
我是在github中下载的sandcastle,链接隧道 https://github.com/EWSoftware/SHFB/releases,下载时需注意版本号,我没有看版本备注就直接下载了最新版本的sandcastle,安装后生成api后直接报错了,不能生成成功。后来排查后发现是版本问题,我的IDE是vs2013,当前sandcastle版本只支持最低vs2015的IDE,所以一直报错。
这个版本中备注描述的很清楚,这是最后一个支持vs2013的版本。
三、配置SandCastle
主要配置详解
3.1 首先打开SandCastle,新建一个文件用来存放sandcastle新建的工程文件,类似vs中新建项目后的解决方案。
3.2 在项目属性中选择需要生成的api类型,如果你想生成类似MSDN帮助文档风格,就可以选择Website。
3.3 Framework version 选择生成解决方案的framework版本号,如果与之不一致,则生成api时会报错
chm类型生成的文档(参考)
website类型
在vs中的引用类按f1可打开该类的帮助文档。
3.4.点击Project Explorer,点击新建的api文件,右击Documentation Sources选择Add Document Source
3.5 选择的类库生成属性中需在输出中xml文档文件复选框打钩在生成,否则生成api无效。
3.6 选择所需生成的类库,也就是后缀名为.csproj的文件即可
四、常见错误
4.1 SHFB: Error BE0043: Unexpected error detected in last build step. See output above for details.
错误信息的意思是缺少程序集的引用,那我就需要把不用的程序集剔除掉,那么如何剔除呢,请看一下操作
4.2 SHFB: Error BE0064: BUILD CANCELLED BY USER
这个错误是由于框架版本不一致所引起的,也就是如果该项目生成时选择的framework版本为4.5,而sandcastle配置的是4.0版本,那么就会报错。
4.3 Sandcastle [丢失<summary> 节点]的问题
遇到这个问题,首先查看代码注释是否有<summary>节点,是否规范。
然后有人会说我明明在代码中已经定义了summary 节点,为什么还会报这种错呢?
这种我尝试最暴力的方法就是让它不提示这个错误,在sandcastle中设置missing tags,取消<summary> elments 的报错信息,点击取消复选框,哪个节点的报错就不会报错。
五、SandCastle在vs中的使用
前面说了都是sandcastle软件的独立使用,还有一种方法是将其集成在vs中使用,使用方法与独立使用相差不大。
如果是已经安装了sandcastle,那么请忽略以下安装步骤。
5.1 在sandcastle目录文件夹下找到后缀为vsix的插件,双击执行,如果弹出此扩展已安装,那么表示安装成功
5.2 在需生成api的项目下添加项目,如果已安装成功,那么在已安装的扩展插件中Documentation就会出现sandcastle插件,输入名称,存放位置,点击确定添加。
5.3.添加完成后,此时的操作和不是集成在vs中的无明显差别,如需生成文档,右击新建的文件,点击生成即可。
六、运行生成API
上面所有步骤完成之后就可以运行sandcastle了,点击build the help file生成
生成成功之后在当前生成目录下,查看生成文件是否齐全,如果文件不全,那么原因在于生成不成功或配置不正确
双击index.html查看api中是否有报错信息,代码是否高亮,链接是否可点。
文档API生成神器SandCastle使用心得的更多相关文章
- 百度地图和高德地图坐标系的互相转换 四种Sandcastle方法生成c#.net帮助类帮助文档 文档API生成神器SandCastle使用心得 ASP.NET Core
百度地图和高德地图坐标系的互相转换 GPS.谷歌.百度.高德坐标相互转换 一.在进行地图开发过程中,我们一般能接触到以下三种类型的地图坐标系: 1.WGS-84原始坐标系,一般用国际GPS纪录仪记 ...
- java 文档自动生成的神器 idoc
写文档 作为一名开发者,每个人都要写代码. 工作中,几乎每一位开发者都要写文档. 因为工作是人和人的协作,产品要写需求文档,开发要写详细设计文档,接口文档. 可是,作为一个懒人,平时最讨厌的一件事情就 ...
- 将C#文档注释生成.chm帮助文档
由于最近需要把以前的一个项目写一个文档,但一时又不知道写成怎样的,又恰好发现了可以生成chm的工具,于是乎我就研究了下,感觉还不错,所以也给大家分享下.好了,不多废话,下面就来实现一下吧. 生成前的准 ...
- 工具分享——将C#文档注释生成.chm帮助文档
由于最近需要把以前的一个项目写一个文档,但一时又不知道写成怎样的,又恰好发现了可以生成chm的工具,于是乎我就研究了下,感觉还不错,所以也给大家分享下.好了,不多废话,下面就来实现一下吧. 生成前的准 ...
- 优于 swagger 的 java markdown 文档自动生成框架-01-入门使用
设计初衷 节约时间 Java 文档一直是一个大问题. 很多项目不写文档,即使写文档,对于开发人员来说也是非常痛苦的. 不写文档的缺点自不用多少,手动写文档的缺点也显而易见: 非常浪费时间,而且会出错. ...
- jQuery全屏滚动插件fullPage.js中文帮助文档API
jQuery全屏滚动插件fullPage.js中文帮助文档API 发现了一个fullPage.js插件,于是百度了一下,还就是这个插件的作用,其实有很多网站都做了全屏滚动的特效,效果也很好看,今天 ...
- springboot成神之——swagger文档自动生成工具
本文讲解如何在spring-boot中使用swagger文档自动生成工具 目录结构 说明 依赖 SwaggerConfig 开启api界面 JSR 303注释信息 Swagger核心注释 User T ...
- VS文档自动生成
VS2008文档自动生成 (发现,Sandcastle主要是用于C#项目.里面的注释都是XML格式的.不太适合VC的.最终还是得用Doxygen) 一.Sandcastle简介: Sandcastle ...
- 将C#文档注释生成.chm帮助文档(转)
由于最近需要把以前的一个项目写一个文档,但一时又不知道写成怎样的,又恰好发现了可以生成chm的工具,于是乎我就研究了下,感觉还不错,所以也给大家分享下.好了,不多废话,下面就来实现一下吧. 生成前的准 ...
随机推荐
- java服务端和用户端
1.server Logintherad: package com.zdsofe.server; import java.io.InputStream; import java.io.OutputSt ...
- ServletContext对象统计在线人数
package com.zdsofe.servlet1; import java.io.IOException; import java.io.PrintWriter; import javax.se ...
- JSP制作简单登陆
JSP制作简单登陆界面 运行环境 eclipse+tomcat+MySQL 不知道的可以参考Jsp运行环境--Tomcat 项目列表 这里我先把jsp文件先放在Web-INF外面访问 需要建立的几个文 ...
- 蓝桥杯比赛javaB组练习《四平方和》
四平方和 四平方和定理,又称为拉格朗日定理:每个正整数都可以表示为至多4个正整数的平方和.如果把0包括进去,就正好可以表示为4个数的平方和. 比如:5 = 0^2 + 0^2 + 1^2 + 2^27 ...
- 推荐60个jQuery插件(转)
jQuery插件jQuery Spin Button自定义文本框数值自增或自减 jQuery插件JQuery Pager分页器实现javascript分页功能 jQuery插件FontSizer实现J ...
- node-xlsx
1.安装 必要组件 npm install node-xlsx -S /*Babel默认只转换新的JavaScript句法(syntax),而不转换新的API,比如Iterator.Generator ...
- 深度学习:Keras入门(二)之卷积神经网络(CNN)
说明:这篇文章需要有一些相关的基础知识,否则看起来可能比较吃力. 1.卷积与神经元 1.1 什么是卷积? 简单来说,卷积(或内积)就是一种先把对应位置相乘然后再把结果相加的运算.(具体含义或者数学公式 ...
- HAUT--1262--魔法宝石(暴力)
1262: 魔法宝石 时间限制: 2 秒 内存限制: 64 MB提交: 525 解决: 157提交 状态 题目描述 小s想要创造n种魔法宝石.小s可以用ai的魔力值创造一棵第i种魔法宝石,或是使用 ...
- JSONP 爬虫
作者QQ:1095737364 QQ群:123300273 欢迎加入! 1.mavne 依赖: <!--html 解析 : jsoup HTML parser library @ ...
- MATLAB实现聚类
%% Cluster x = data; % 传入数据 [h, w] = size(x); num_cluster = 12; % 聚类数 T = clusterdata(x, num_cluster ...