Updating Rafy Help Documentation with MarkDown & DocFX

The Rafy framework's help documentation has recently been updated with DocFX.

SandCastle

Previously, the help documentation of the Rafy framework was written using SandCastle ( https://github.com/EWSoftware/SHFB ). As shown below:

Each of its documents is an .aml file. aml file is a custom formatted xml file. An example is as follows:

<?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>

The advantage of using xml to write documents is that the format is relatively standardized. In this way, SandCastle can generate it in many standard document formats:

The generated website is as shown below:

The open source address of SandCastle is: https://github.com/EWSoftware/SHFB .

For the specific usage of SandCastle, please refer to: " Document API Generation Artifact SandCastle Usage Experience ".

DocFX

In the past two years, MS's own help documents have changed greatly, such as MSDN: " C# Guide ".

It uses the latest document writing and generating tool: DocFX. URL for DocFX: http://dotnet.github.io/docfx/ .

For help, you can take a look at this: " docfx makes a document platform like Microsoft "

Simply put, docFX supports the use of markdown to write documentation. And finally generate the corresponding website.

Markdown is a simple markup language. Most of the documentation is currently written in this language. For example, the wiki of each project in Github is written in markdown. In addition, the blogs I wrote in the blog garden are currently written directly using markdown. Easy to use, obvious format, high writing efficiency, what you see is what you get, and good code compatibility.

For example, the article in the example above, transformed as follows:

## 简介
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 + 多数据库支持

In addition, due to the large number of documents, we wrote a small tool to convert all the help documents of the entire Rafy from xml format files to markdown syntax. Then through docFX to generate the entire website.

For the latest document after generation, see: " Introduction to Rafy Framework ", which uses the default skin of DocFX, as shown below:

After this upgrade, it will be easier to write documentation in the future. You can write quickly by using markdown directly. Then use DocFX to generate a WebSite with one click and upload it directly to Github Pages.

The source code of the current document has also been uploaded to Github: https://github.com/zgynhqf/Rafy/tree/master/Rafy/_Items/Documentation, interested friends can take a look .