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

最近使用 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 ，有兴趣的朋友能够看看。