最近使用 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"><developerConceptualDocumentxmlns="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.dll2. WPF 客戶端生成框架（暫未發布）包含以下程序集：* Rafy.WPF.Controls.dll* Rafy.WPF.dll3. Web：B/S 界面生成框架（暫未發布）包含以下程序集：- Rafy.Web.dll4. 報表（暫未發布）...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 + SOARafy.Domain DDD = Controller + Repository + 可擴展屬性的EntityRafy.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 ，有興趣的朋友可以看看。

總結

以上是生活随笔為你收集整理的使用 MarkDown DocFX 升级 Rafy 帮助文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。