使用 MarkDown & DocFX 升级 Rafy 帮助文档
2024-08-31 07:31:22
**
**
最近使用 DocFX 对 Rafy 框架的帮助文档进行了升级。
SandCastle
之前 Rafy 框架的帮助文档，是使用 SandCastle 来编写的（https://github.com/EWSoftware/SHFB）。如下图：
其文档中的每一个文档都是一个 .aml 文件。aml 文件是一种自定义格式的 xml 文件。示例如下：
<?xml version="1.0" encoding="utf-8"?>
<topic id="69b641cf-d1fe-4f06-877f-b479d268a3fc" revisionNumber="1">
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>Rafy 帮助文档</para>
<para>文档版本号：0.5.544</para>
</introduction>
<section address="intro">
<title>简介</title>
<content>
<para>Rafy 是一个面向企业级开发的插件化快速开发框架。前生为 OEA（OpenExpressApp），09 年 10 月发布 1.0 版本，12 年 4 月发布了 2.0。其目标主要专注于：</para>
<list class="bullet">
<listItem>
<para>快速开发：</para>
<para>领域驱动设计、界面自动生成、数据库自动生成与升级、易用的业务逻辑编写框架。</para>
</listItem>
<listItem>
<para>产品线工程：</para>
<para>插件化业务模块积累（内置一个多个现有的插件模块）、客户化二次开发、实施配置平台。</para>
</listItem>
<listItem>
<para>一套代码，可同时生成并运行 C/S、单机版、B/S 三种应用程序。</para>
<para>C/S版本 与 单机版 代码重用率 100%。</para>
<para>C/S版本 与 B/S版本 重用服务端代码（完全重用服务层以下代码。结合界面生成，只需要编写少量的界面层控制代码即可。）。</para>
</listItem>
<listItem>
<para>与 Visual Studio 集成</para>
<para>Rafy 的一个重要作用就是为了提升开发效率，所以我们为 VisualStudio 开发了 RafySDK 插件，其中包含项目模板、代码生成、领域建模等功能。一体化的开发环境，可以更加快速地开发 Rafy 应用程序。</para>
</listItem>
</list>
</content>
</section>
<section address="includes">
<title>组成部分</title>
<content>
<para>它包含了以下组成部分：</para>
<list class="bullet">
<listItem>
<para>Rafy 领域实体框架</para>
<para>
Rafy <link xlink:href="c8e6cd25-c674-4cd1-9880-816d11f58eb8" /> 是一个 ORM 框架，可脱离 Rafy 框架其它组件单独运行，为开发人员提供了极高的开发效率、强大的功能。同时集领域驱动设计、面向服务架构、模型驱动架构、产品线工程方法于一身，是 Rafy 框架中其它组件（如界面生成等高级功能）的基础。
</para>
<para>包含以下程序集：</para>
<list class="bullet">
<listItem>
<para>Rafy.dll</para>
</listItem>
</list>
</listItem>
<listItem>
<para>WPF 客户端生成框架（暂未发布）</para>
<para>包含以下程序集：</para>
<list class="bullet">
<listItem>
<para>Rafy.WPF.Controls.dll</para>
</listItem>
<listItem>
<para>Rafy.WPF.dll</para>
</listItem>
</list>
</listItem>
<listItem>
<para>Web：B/S 界面生成框架（暂未发布）</para>
<para>包含以下程序集：</para>
<list class="bullet">
<listItem>
<para>Rafy.Web.dll</para>
</listItem>
</list>
</listItem>
<listItem>
<para>报表（暂未发布）</para>
<para>...</para>
</listItem>
<listItem>
<para>自动化测试（暂未发布）</para>
<para>...</para>
</listItem>
</list>
</content>
</section>
<section address="important">
<title>框架发布记录</title>
<content>
<para>
详见：<externalLink>
<linkText>Rafy(原OEA)领域实体框架发布主页</linkText>
<linkUri>http://www.cnblogs.com/zgynhqf/p/3356692.html</linkUri>
</externalLink>
</para>
</content>
</section>
<section address="optionalAddress">
<title>辅助说明</title>
<content>
<para>
Rafy = ProductLine + MDA + Plugins + Rafy.Domain + Rafy.UI(AutoUI)
</para>
<para>
Rafy.Domain = DDD + ORM + Distributed + SOA
</para>
<para>
Rafy.Domain DDD = Controller + Repository + 可扩展属性的Entity
</para>
<para>
Rafy.Domain ORM = 可扩展属性的Entity + 易用的Linq + SqlTree + 高性能Mapping + AutoDB + 多数据库支持
</para>
</content>
</section>
<relatedTopics>
</relatedTopics>
</developerConceptualDocument>
</topic>
使用 xml 来编写文档的好处在于格式比较规范。这样，SandCastle 可以将其生成许多标准的文档格式：
生成后的网站，如下图所示：
SandCastle 的开源地址是：https://github.com/EWSoftware/SHFB。
关于 SandCastle 的具体使用方法，可以见：《文档API生成神器SandCastle使用心得》。
DocFX
最近两年，MS 自家的帮助文档大变样，例如 MSDN：《C# Guide》。
其使用的就是最新的文档编写、生成工具：DocFX。DocFX 的网址：http://dotnet.github.io/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.dll
2. WPF 客户端生成框架（暂未发布）
包含以下程序集：
* Rafy.WPF.Controls.dll
* Rafy.WPF.dll
3. Web：B/S 界面生成框架（暂未发布）
包含以下程序集：
- Rafy.Web.dll
4. 报表（暂未发布）
...
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 + SOA
Rafy.Domain DDD = Controller + Repository + 可扩展属性的Entity
Rafy.Domain ORM = 可扩展属性的Entity + 易用的Linq + SqlTree + 高性能Mapping + AutoDB + 多数据库支持
另外，由于文档较多，所以我们编写了一个小工具，将整个 Rafy 的所有帮助文档，从 xml 格式文件转换为 markdown 语法。然后再通过 docFX 来生成整个网站。
生成后最新的文档，见：《Rafy 框架简介》，使用的是 DocFX 的默认的皮肤，如下图：
这次升级后，以后再编写文档就比较简单了。直接使用 markdown 就可以快速编写了。然后使用 DocFX 一键生成 WebSite，直接上传到 Github Pages 就行了。
当前文档的源码也上传到 Github 了：https://github.com/zgynhqf/Rafy/tree/master/Rafy/_Items/Documentation ，有兴趣的朋友可以看看。
最新文章
- Check a dll is x64 or x86
- 调整ESX的VMFS磁盘格式的块大小，让单个虚拟磁盘支持更大容量
- Android长时间后台运行Service
- Extjs4.1中图片数据源
- php文件上传之单文件上传
- easyui dataBox 增加一天，减少一天
- Androidndk开发打包时我们应该如何注意平台的兼容（x86,arm,arm-v7a）
- diskpart修改盘符
- javascript 三种弹出对话框
- python的IDE(pycharm)安装以及简单配置
- js饼状图（带百分比）功能实现，新人必懂
- angular ，require.js， angular-async-loader实现单页面路由，控制器js文件分离
- java DOM
- 测试那些事儿—软测必备的Linux知识（三）
- Druid密码加密
- eclipse安装中文语言包
- c# 为什么要使用Array、ArrayList、List?
- STM32F4 Alternate function mapping
- 【转载】WebDriver(C#)之十点使用心得
- Could not apply the stored configuration for monitors