【DocFX文档翻译】DocFX 入门 (Getting Started with DocFX)

时间 2019-11-25

标签 DocFX文档翻译 docfx 入门 getting started 繁體版

原文原文链接

DocFX 入门

DocFX 是一个基于.NET的API文档生成器，当前支持 C# 和 VB。
它能够经过你的代码中的三斜杠注释生成 API 参考文档。一样也支持你使用 Markdown 文件建立一些其余的主题文档（例如：教程以及使用手册）。以及自定义生成的参考文档。
node

DocFX 会使用你的代码以及 Markdown 文件生成一个静态的 HTML 网站。你能够将它轻松的部署到任何web 服务器（例如： github.io）。一样的 DocFX 也提供扩展性，容许你经过模版自定义网站的布局和样式.
git

若是你有兴趣使用你本身的样式建立你的网站，你能够参考如何建立自定义模版来建立你的本身的模版。
github

DocFX 还包含如下很酷的功能：
web

和你的代码紧密集成。你能够在文档中点击 "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。

第1步. DocFX 被打包成 chocolatey 包.
能够经过 Chocolatey 调用命令 cinst docfx -y 来安装。json

另外, 你也能够从https://github.com/dotnet/docfx/releases 下载docfx.zip文件, 并解压到本地目录, 把程序路径添加到 PATH 环境变量这样你能够在任何环境调用它。
api

第2步. 建立实例项目
服务器

docfx init -q

命令行会生成一个名为 docfx_project 的默认项目。
markdown

第3步. 编译网站app

docfx docfx_project\docfx.json --serve

如今能够经过访问 http://localhost:8080 浏览生成网站了.
less

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

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

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

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

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

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

[!提示]
将不一样类型的文件放入不一样的目录是一个好习惯。

Q: 如何在api中快速引用其余 API 或者 c?
A: Use @uid syntax.
Q: uid 是什么，我怎么去找 uid?
A: 参考 DFM 交叉引用章节。
Q: 如何在网站中快速找到 uid ?
A: 在生成网站中, 点击 F12 查看源代码,查看API标题. 你会在data-uid标签中找到 uid。