【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 属性：

[!NOTE]
> *Possible warning*:
> - *Cache is corrupted*: if your project targets multiple frameworks, you have to indicate one to be the main for the documentation, through the [`TargetFramework` property](https://github.com/dotnet/docfx/issues/1254#issuecomment-294080535) in `docfx.json`: -->

 "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

[!NOTE]
> *Known issue in AppVeyor*: Currently `platform: Any CPU` in *appveyor.yml* causes `docfx metadata` failure. 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

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

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

1. DocFX 种子项目要

---

这里有一个种子项目 https://github.com/docascode/docfx-seed. 包含

1. src 目录中有个基本的 C# 项目。
2. articles 目录中有一些说明文档。
3. 一个可覆盖的文件，在“specs”下添加额外的内容到API
4. 根目录下的 toc.yml 文件。生成网站的导航栏。
5. 根目录下的 docfx.json 文件。 docfx 的配置文件。

<!-- 6. A seed project to play with DocFX

Here is a seed project https://github.com/docascode/docfx-seed. It contains

1. A basic C# project under src.
2. Several conceptual files under articles.
3. An overwrite file to add extra content to API under specs.
4. toc.yml under root folder. It renders as the navbar of the website.
5. docfx.json under root folder. It is the configuration file that docfx depends upon. -->

[!提示]

将不同类型的文件放入不同的目录是一个好习惯。

[!Tip]
> It is a good practice to separate files with different type into different folders. -->

1. 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。

<!-- 7. Q&A

1. Q: How do I quickly reference APIs from other APIs or c?
   
   A: Use @uid syntax.
2. Q: What is uid and where do I find uid?
   
   A: Refer to Cross Reference section in DFM.
3. Q: How do I quickly find uid in the website?
   
   A: In the generated website, hit F12 to view source, and look at the title of an API. You can find uid in data-uid attribute. -->