使用 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 使用 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，有興趣的朋友可以看看。
使用 MarkDown & DocFX 升級 Rafy 幫助文檔