使用 MarkDown & DocFX 升級 Rafy 幫助文檔

時間 2019-11-06

標籤使用 markdown docfx 升級 rafy 幫助文檔欄目 Markdown 简体版

原文原文鏈接

最近使用 DocFX 對 Rafy 框架的幫助文檔進行了升級。html

SandCastle

以前 Rafy 框架的幫助文檔，是使用 SandCastle 來編寫的（https://github.com/EWSoftware/SHFB）。以下圖：git

其文檔中的每個文檔都是一個 .aml 文件。aml 文件是一種自定義格式的 xml 文件。示例以下：github

<?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 能夠將其生成許多標準的文檔格式：數據庫

生成後的網站，以下圖所示：markdown

SandCastle 的開源地址是：https://github.com/EWSoftware/SHFB。架構

關於 SandCastle 的具體使用方法，能夠見：《文檔API生成神器SandCastle使用心得》。app

DocFX

最近兩年，MS 自家的幫助文檔大變樣，例如 MSDN：《C# Guide》。框架

其使用的就是最新的文檔編寫、生成工具：DocFX。DocFX 的網址：http://dotnet.github.io/docfx/。ide

使用幫助，能夠看看這篇：《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 ，有興趣的朋友能夠看看。