【DocFX文檔翻譯】DocFX 入門 (Getting Started with DocFX)

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。