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

kiler發表於2017-08-14

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 已知問題: 當前 appveyor.yml 中的配置 platform: Any CPU 會導致 docfx metadata 失敗。 https://github.com/dotnet/docfx/issues/1078

  1. 從原始碼生成

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

第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。

相關文章