【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 浏览生成网站了.

3. 在 Visual Studio 中集成DocFX。

---

Step2. 编译项目, 项目里面会生成一个 _site 文件夹。

[!注意]
可能会出现的警告:

• Cache is corrupted:如果项目目标是多framework, 你不得不为文档指定一个主framework, 通过设置 docfx.json 文件的 TargetFramework 属性：

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

4. 使用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

5. 从源代码生成

---

作为前置条件, 你必须具备:

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