DocFX 入門

1. DocFX 是什么？

DocFX 是一個基于.NET的API文檔生成器，當前支持 C# 和 VB。
它可以通過你的代碼中的三斜杠注釋生成 API 參考文檔。同樣也支持你使用 Markdown 文件創建一些其他的主題文檔（例如：教程以及使用手冊）。以及自定義生成的參考文檔。

DocFX 會使用你的代碼以及 Markdown 文件生成一個靜態的 HTML 網站。你可以將它輕松的部署到任何web 服務器（例如： github.io）。同樣的 DocFX 也提供擴展性，允許你通過模版自定義網站的布局和樣式.

如果你有興趣使用你自己的樣式創建你的網站，你可以參考 如何創建自定義模版 來創建你的自己的模版。

DocFX 還包含以下很酷的功能：

• 和你的代碼緊密集成。你可以在文檔中點擊 "View Source" 鏈接導航到github上對應的源代碼(你的代碼必須發布到 GitHub )。
• 跨平臺的支持。擁有Windows平臺以及.NET Core 的跨平臺 exe程序。
• 和Visual Studio集成. 你可以在Visual Studio 中無縫使用 DocFX 。
• Markdown 擴展。我們推薦DocFX Flavored Markdown(DFM) 格式來編寫文檔。 DFM 100% 兼容 GitHub Flavored Markdown(GFM) 并且添加了一些有用的擴展,例如 file inclusion（ 文件包含）, code snippet（ 代碼片段）, cross reference（ 交叉引用）, 以及 yaml header。
  更多關于 DFM 的信息, 請參考 DFM。

2. 使用 DocFX 命令行工具

第1步. DocFX 被打包成 chocolatey 包.
可以通過 Chocolatey 調用命令 cinst docfx -y 來安裝。

另外, 你也可以從https://github.com/dotnet/docfx/releases 下載docfx.zip文件, 并解壓到本地目錄, 把程序路徑添加到 PATH 環境變量這樣你可以在任何環境調用它。

第2步. 創建實例項目

docfx init -q

命令行會生成一個名為 docfx_project 的默認項目。

第3步. 編譯網站

docfx docfx_project\docfx.json --serve

現在可以通過訪問 http://localhost:8080 瀏覽生成網站了.

1. 在 Visual Studio 中集成DocFX。
   
   ---------------

Step2. 編譯項目, 項目里面會生成一個 _site 文件夾。

[!注意]
可能會出現的警告:

• Cache is corrupted:如果項目目標是多framework, 你不得不為文檔指定一個主framework, 通過設置 docfx.json 文件的 TargetFramework 屬性：

 "metadata": [
   {
     "src": "...",
     "dest": "...",
     "properties": {
       "TargetFramework": <one_of_your_framework>
     }
   },
 ]

1. 使用DocFX 生成服務
   
   ---------------

DocFX 可以在持續集成環境中使用。

大部分編譯系統不會檢查分支是否被生成，但是如果使用 detached head 來指定提交，DoxFX 需要分支名賴在api 文檔中實現 View Source 鏈接。

設置 DOCFX_SOURCE_BRANCH_NAME 環境變量告知 DocFX 使用哪個分支。

需要編譯系統支持分支名環境變量. DocFX 使用以下變量：

• APPVEYOR_REPO_BRANCH - AppVeyor
• BUILD_SOURCEBRANCHNAME - Visual Studio Team Services
• CI_BUILD_REF_NAME - GitLab CI
• Git_Branch - TeamCity
• GIT_BRANCH - Jenkins
• GIT_LOCAL_BRANCH - Jenkins

[!注意]
AppVeyor 已知問題: 當前 appveyor.yml 中的配置 platform: Any CPU 會導致 docfx metadata 失敗。 https://github.com/dotnet/docfx/issues/1078

1. 從源代碼生成
   
   ----------------
   作為前置條件, 你必須具備:

• Visual Studio 2017 安裝 .NET Core cross-platform development 工具集
• Node.js
  

第1步. git clone https://github.com/dotnet/docfx.git 獲取最新代碼。

第2步. 運行根目錄下的 build.cmd 。

第3步. 在IDE的 nuget 源中增加 artifacts 目錄:

Tools > NuGet Package Manager > Package Manager Settings > Package Sources

Step4. 按照之前的 #2, #3, #4 步驟在命令行，IDE 或者.NET Core中使用 DocFX 。

6. DocFX 種子項目要

這里有一個種子項目 https://github.com/docascode/docfx-seed. 包含

1. src 目錄中有個基本的 C# 項目。
2. articles 目錄中有一些說明文檔。
3. 一個可覆蓋的文件，在“specs”下添加額外的內容到API
4. 根目錄下的 toc.yml 文件。生成網站的導航欄。
5. 根目錄下的 docfx.json 文件。 docfx 的配置文件。

[!提示]
將不同類型的文件放入不同的目錄是一個好習慣。

7. Q&A

1. Q: 如何在api中快速引用其他 API 或者 c?
   A: Use @uid syntax.
2. Q: uid 是什么，我怎么去找 uid?
   A: 參考 DFM 交叉引用 章節。
3. Q: 如何在網站中快速找到 uid ?
   A: 在生成網站中, 點擊 F12 查看源代碼,查看API標題. 你會在data-uid標簽中找到 uid。