使用 MarkDown & DocFX 升级 Rafy 帮助文档

img

最近使用 DocFX 对 Rafy 框架的帮助文档进行了升级。

SandCastle

之前 Rafy 框架的帮助文档,是使用 SandCastle 来编写的(https://github.com/EWSoftware/SHFB)。如下图:

使用 MarkDown & DocFX 升级 Rafy 帮助文档_第1张图片

其文档中的每一个文档都是一个 .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 可以将其生成许多标准的文档格式:

使用 MarkDown & DocFX 升级 Rafy 帮助文档_第2张图片

生成后的网站,如下图所示:

使用 MarkDown & DocFX 升级 Rafy 帮助文档_第3张图片

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 升级 Rafy 帮助文档_第4张图片

这次升级后,以后再编写文档就比较简单了。直接使用 markdown 就可以快速编写了。然后使用 DocFX 一键生成 WebSite,直接上传到 Github Pages 就行了。

当前文档的源码也上传到 Github 了:https://github.com/zgynhqf/Rafy/tree/master/Rafy/_Items/Documentation ,有兴趣的朋友可以看看。

你可能感兴趣的:(使用 MarkDown & DocFX 升级 Rafy 帮助文档)