DocFX 入門
===============

1. DocFX 是什么檬果？

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

DocFX 會(huì)使用你的代碼以及 Markdown 文件生成一個(gè)靜態(tài)的 HTML 網(wǎng)站酌予。你可以將它輕松的部署到任何web 服務(wù)器（例如： github.io）磺箕。同樣的 DocFX 也提供擴(kuò)展性，允許你通過(guò)模版自定義網(wǎng)站的布局和樣式.

如果你有興趣使用你自己的樣式創(chuàng)建你的網(wǎng)站抛虫，你可以參考 如何創(chuàng)建自定義模版 來(lái)創(chuàng)建你的自己的模版松靡。

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

• 和你的代碼緊密集成。你可以在文檔中點(diǎn)擊 "View Source" 鏈接導(dǎo)航到github上對(duì)應(yīng)的源代碼(你的代碼必須發(fā)布到 GitHub )建椰。
• 跨平臺(tái)的支持雕欺。擁有Windows平臺(tái)以及.NET Core 的跨平臺(tái) exe程序。
• 和Visual Studio集成. 你可以在Visual Studio 中無(wú)縫使用 DocFX 。
• Markdown 擴(kuò)展阅茶。我們推薦DocFX Flavored Markdown(DFM) 格式來(lái)編寫文檔蛛枚。 DFM 100% 兼容 GitHub Flavored Markdown(GFM) 并且添加了一些有用的擴(kuò)展,例如 file inclusion（ 文件包含）, code snippet（ 代碼片段）, cross reference（ 交叉引用）, 以及 yaml header谅海。
  更多關(guān)于 DFM 的信息, 請(qǐng)參考 DFM脸哀。

2. 使用 DocFX 命令行工具

第1步. DocFX 被打包成 chocolatey 包.
可以通過(guò) Chocolatey 調(diào)用命令 cinst docfx -y 來(lái)安裝。

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

第2步. 創(chuàng)建實(shí)例項(xiàng)目

docfx init -q

命令行會(huì)生成一個(gè)名為 docfx_project 的默認(rèn)項(xiàng)目撞蜂。

第3步. 編譯網(wǎng)站

docfx docfx_project\docfx.json --serve

現(xiàn)在可以通過(guò)訪問(wèn) http://localhost:8080 瀏覽生成網(wǎng)站了.

3. 在 Visual Studio 中集成DocFX。
   

Step2. 編譯項(xiàng)目, 項(xiàng)目里面會(huì)生成一個(gè) _site 文件夾侥袜。

[!注意]
可能會(huì)出現(xiàn)的警告:

• Cache is corrupted:如果項(xiàng)目目標(biāo)是多framework, 你不得不為文檔指定一個(gè)主framework, 通過(guò)設(shè)置 docfx.json 文件的 TargetFramework 屬性：

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

4. 使用DocFX 生成服務(wù)
   

DocFX 可以在持續(xù)集成環(huán)境中使用蝌诡。

大部分編譯系統(tǒng)不會(huì)檢查分支是否被生成，但是如果使用 detached head 來(lái)指定提交枫吧，DoxFX 需要分支名賴在api 文檔中實(shí)現(xiàn) View Source 鏈接浦旱。

設(shè)置 DOCFX_SOURCE_BRANCH_NAME 環(huán)境變量告知 DocFX 使用哪個(gè)分支。

需要編譯系統(tǒng)支持分支名環(huán)境變量. 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 已知問(wèn)題: 當(dāng)前 appveyor.yml 中的配置 platform: Any CPU 會(huì)導(dǎo)致 docfx metadata 失敗九杂。 https://github.com/dotnet/docfx/issues/1078

5. 從源代碼生成
   

作為前置條件, 你必須具備:

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

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

第2步. 運(yùn)行根目錄下的 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 種子項(xiàng)目要

這里有一個(gè)種子項(xiàng)目 https://github.com/docascode/docfx-seed. 包含

1. src 目錄中有個(gè)基本的 C# 項(xiàng)目。
2. articles 目錄中有一些說(shuō)明文檔镀层。
3. 一個(gè)可覆蓋的文件镰禾，在“specs”下添加額外的內(nèi)容到API
4. 根目錄下的 toc.yml 文件。生成網(wǎng)站的導(dǎo)航欄唱逢。
5. 根目錄下的 docfx.json 文件吴侦。 docfx 的配置文件。

[!提示]
將不同類型的文件放入不同的目錄是一個(gè)好習(xí)慣坞古。

7. Q&A

1. Q: 如何在api中快速引用其他 API 或者 c?
   A: Use @uid syntax.
2. Q: uid 是什么备韧，我怎么去找 uid?
   A: 參考 DFM 交叉引用 章節(jié)。
3. Q: 如何在網(wǎng)站中快速找到 uid ?
   A: 在生成網(wǎng)站中, 點(diǎn)擊 F12 查看源代碼,查看API標(biāo)題. 你會(huì)在data-uid標(biāo)簽中找到 uid绸贡。