最近使用 DocFX 对 Rafy 框架的帮助文档进行了升级。
SandCastle
之前 Rafy 框架的帮助文档，是使用 SandCastle 来编写的（）。如下图：
其文档中的每一个文档都是一个 .aml 文件。aml 文件是一种自定义格式的 xml 文件。示例如下：
Rafy 帮助文档 文档版本号：0.5.544 简介 Rafy 是一个面向企业级开发的插件化快速开发框架。前生为 OEA（OpenExpressApp），09 年 10 月发布 1.0 版本，12 年 4 月发布了 2.0。其目标主要专注于：
快速开发： 领域驱动设计、界面自动生成、数据库自动生成与升级、易用的业务逻辑编写框架。 产品线工程： 插件化业务模块积累（内置一个多个现有的插件模块）、客户化二次开发、实施配置平台。 一套代码，可同时生成并运行 C/S、单机版、B/S 三种应用程序。 C/S版本 与 单机版 代码重用率 100%。 C/S版本 与 B/S版本 重用服务端代码（完全重用服务层以下代码。结合界面生成，只需要编写少量的界面层控制代码即可。）。 与 Visual Studio 集成 Rafy 的一个重要作用就是为了提升开发效率，所以我们为 VisualStudio 开发了 RafySDK 插件，其中包含项目模板、代码生成、领域建模等功能。一体化的开发环境，可以更加快速地开发 Rafy 应用程序。 组成部分 它包含了以下组成部分：
Rafy 领域实体框架 Rafy 是一个 ORM 框架，可脱离 Rafy 框架其它组件单独运行，为开发人员提供了极高的开发效率、强大的功能。同时集领域驱动设计、面向服务架构、模型驱动架构、产品线工程方法于一身，是 Rafy 框架中其它组件（如界面生成等高级功能）的基础。 包含以下程序集：
Rafy.dll WPF 客户端生成框架（暂未发布） 包含以下程序集：
Rafy.WPF.Controls.dll Rafy.WPF.dll Web：B/S 界面生成框架（暂未发布） 包含以下程序集：
Rafy.Web.dll 报表（暂未发布） ... 自动化测试（暂未发布） ... 框架发布记录 详见： Rafy(原OEA)领域实体框架发布主页 http://www.cnblogs.com/zgynhqf/p/3356692.html 辅助说明 Rafy = ProductLine + MDA + Plugins + Rafy.Domain + Rafy.UI(AutoUI) Rafy.Domain = DDD + ORM + Distributed + SOA Rafy.Domain DDD = Controller + Repository + 可扩展属性的Entity Rafy.Domain ORM = 可扩展属性的Entity + 易用的Linq + SqlTree + 高性能Mapping + AutoDB + 多数据库支持
使用 xml 来编写文档的好处在于格式比较规范。这样，SandCastle 可以将其生成许多标准的文档格式：
生成后的网站，如下图所示：
SandCastle 的开源地址是：。
关于 SandCastle 的具体使用方法，可以见：《》。
DocFX
最近两年，MS 自家的帮助文档大变样，例如 MSDN：《》。
其使用的就是最新的文档编写、生成工具：DocFX。DocFX 的网址：。
使用帮助，可以看看这篇：《》
简单地说，docFX 支持使用 markdown 来编写文档。并最终生成对应的网站。
Markdown 是一个简单标记语言。目前大多数的文档编写都流行使用这个语言。例如 Github 中每个项目的 Wiki 都是使用 markdown 来编写。另外，我个人在博客园编写的这些的博客，目前也都是使用 markdown 来直接编写。易用、格式明显、编写效率高、所见即所得、对代码的兼容性好。
例如，上面示例中的文章，转换后如下：
## 简介Rafy 是一个面向企业级开发的插件化快速开发框架。前生为 OEA（OpenExpressApp），09 年 10 月发布 1.0 版本，12 年 4 月发布了 2.0。其目标主要专注于： - 快速开发： DDD、界面自动生成、数据库自动生成与升级、易用的业务逻辑编写框架。 - 产品线工程： 插件化业务模块积累（内置一个权限控制插件模块）、客户化二次开发、实施配置平台。 - 一套代码，可同时生成并运行 C/S、单机版、B/S 三种应用程序。 C/S版本 与 单机版 代码重用率 100%。 C/S版本 与 B/S版本 重用服务端代码（完全重用服务层以下代码。结合界面生成，只需要编写少量的界面层控制代码即可。）。 - 与 Visual Studio 集成 Rafy 的一个重要作用就是为了提升开发效率，所以我们为 VisualStudio 开发了 RafySDK 插件，其中包含项目模板、代码生成、领域建模等功能。一体化的开发环境，可以更加快速地开发 Rafy 应用程序。##组成部分它包含了以下组成部分：1. 领域实体框架 [领域实体框架](领域实体框架.html)是一个 ORM 框架，可脱离 Rafy 框架其它组件单独运行，为开发人员提供了极高的开发效率、强大的功能。同时集领域驱动设计、面向服务架构、模型驱动架构、产品线工程方法于一身，是 Rafy 框架中其它组件（如界面生成等高级功能）的基础。 包含以下程序集： * Rafy.dll2. WPF 客户端生成框架（暂未发布） 包含以下程序集： * Rafy.WPF.Controls.dll * Rafy.WPF.dll3. Web：B/S 界面生成框架（暂未发布） 包含以下程序集： - Rafy.Web.dll4. 报表（暂未发布） ...5. 自动化测试（暂未发布） ...##框架发布记录详见：[Rafy(原OEA)领域实体框架发布主页](http://www.cnblogs.com/zgynhqf/p/3356692.html)##辅助说明Rafy = ProductLine + MDA + Plugins + Rafy.Domain + Rafy.UI(AutoUI)Rafy.Domain = DDD + ORM + Distributed + SOARafy.Domain DDD = Controller + Repository + 可扩展属性的EntityRafy.Domain ORM = 可扩展属性的Entity + 易用的Linq + SqlTree + 高性能Mapping + AutoDB + 多数据库支持
另外，由于文档较多，所以我们编写了一个小工具，将整个 Rafy 的所有帮助文档，从 xml 格式文件转换为 markdown 语法。然后再通过 docFX 来生成整个网站。
生成后最新的文档，见：《》，使用的是 DocFX 的默认的皮肤，如下图：
这次升级后，以后再编写文档就比较简单了。直接使用 markdown 就可以快速编写了。然后使用 DocFX 一键生成 WebSite，直接上传到 Github Pages 就行了。
当前文档的源码也上传到 Github 了： ，有兴趣的朋友可以看看。