介绍

DocFx安装

Visual Studio中的测试解决方案

使用docfx init设置DocFx

手动设置DocFx

docfx.json配置文件的剖析

元数据部分

构建部分

docs文件夹

filterConfig.yml文件

概念文档和TOC（目录）文件

.gitignore文件

生成文档站点

将生成的文档站点发布到GitHub Pages

PDF历险记

经过测试

在本文中，我们将使用DocFx为Windows计算机中的Visual Studio C＃解决方案生成文档。

从GitHub下载源代码

介绍

DocFx是生成文档的命令行工具。

DocFx建立了一个结合两个来源的文档网站：

它从源代码文件中的注释中收集参考文档
由用户以Markdown文件形式提供给DocFx的概念性文档

根据DocFx网站：

“DocFX可以从源代码（包括.NET，REST，JavaScript，Java，Python和TypeScript）以及原始Markdown文件中生成文档。”

并且：

“DocFX可以在Linux，macOS和Windows上运行。生成的静态网站可以部署到任何主机，例如GitHub Pages或Azure网站，而无需进行其他配置。”

DocFx是由Microsoft开发的一种开源工具，正如该公司所说，它是用于构建Microsoft文档网站的工具。

在本文中，我们将使用DocFx为Windows计算机中的Visual Studio C＃解决方案生成文档。

DocFx安装

下载和安装DocFx的最简单方法是使用Windows版Chocolatey软件包管理器。以管理员身份打开终端并执行以下操作：

choco install docfx -y

上面也将DocFx添加到PATH环境变量中。

Visual Studio中的测试解决方案

打开Visual Studio并使用两个项目创建一个解决方案：一个Library项目和一个Windows Forms项目。

这是文件夹结构：

Solution+ App+ LibSolution.sln

对于每个项目，请转到属性|生成并选中XML文档文件复选框。

向项目中添加一些类并记录这些类。这是通过在类、方法和属性上添加三斜杠注释来完成的。

构建解决方案。

使用docfx init设置DocFx

DocFx文档提供了两个演练。

这些演练说明，我们通过打开终端cd到solutionF文件夹init DocFx ，然后键入docfx init -q以初始化项目。

cd C:\Solution
docfx init -q

-q参数用于quiet。否则，它会遇到用户必须回答的一系列问题。

上面的代码在根解决方案文件夹中创建了一个docfx_project文件夹，并向其中添加了许多子文件夹和文件。其中最重要的文件docfx_project是docfx.json文件，它是DocFx的配置文件。

“docfx.json是docfx用于生成文档的配置文件”

生成的docfx.json中的所有文件夹引用都是错误的。并且根本不需要某些创建的文件夹。

因此，删除docfx_project文件夹。我们将使用自己的方式。

手动设置DocFx

我们在根解决方案文件夹中需要一个子文件夹，用于DocFx文件和生成的文档。创建新文件夹并命名DocFx。

Solution+ App+ DocFx+ LibSolution.sln

在DocFx文件夹中，创建一个空的docfx.json，使用Visual Studio打开它并添加以下内容：

{"metadata": [{"src": [{"files": [ "**/**.csproj" ],"src": ".."}],"dest": "reference","disableGitFeatures": false,"disableDefaultFilter": false,"filter": "filterConfig.yml"}],"build": {"content": [{"files": ["reference/**.yml","reference/index.md"]},{"files": ["Concepts/toc.yml","Concepts/**.md","Concepts/**/toc.yml","toc.yml","*.md"]}],"resource": [{"files": [ "images/**" ]}],"dest": "../docs","globalMetadataFiles": [],"fileMetadataFiles": [],"template": [ "default" ],"postProcessors": [],"markdownEngineName": "markdig","noLangKeyword": false,"keepFileLink": false,"cleanupCacheHistory": false,"disableGitFeatures": false}
}

docfx.json配置文件的剖析

该docfx.json包含两个部分：metadata和build。可能会有第三部分，pdf，但我们稍后再讨论这种冒险。

元数据部分

metadata部分对DocFx来说：

在哪里找到源代码文件，从中收集注释
将收集的材料放在哪里
以及如何过滤源文件中发现的类型的固有成员

我们的metadata部分对DocFx来说：

从rool解决方案文件夹（"src": ".."）开始在所有csproj文件（"files": [ "**/**.csproj" ]）中查找源代码文件
将收集的资料放置到名为reference（"dest": "reference",）的文件夹中
并根据提供的yml文件（"filter": "filterConfig.yml"）过滤继承的成员

该引用文件夹将由DocFx创建，如果不存在。

构建部分

Build部分对DocFx来说：

对于两种类型，从哪里找到要构建的内容，从源文件收集的DocFx内容（引用上）和用户作为Markdown文件提供的内容（概念上）
在哪里可以找到Markdown文件中使用的图像
“已编译”输出的位置，即它生成的网站
以及使用什么模板

我们的build部分对DocFx来说：

参考内容位于参考文件夹中，而概念内容位于概念文件夹中
图像在图像文件夹中
将生成的网站放置到../docs文件夹（"dest": "../docs"）
并使用default模板

docs文件夹

我们指示DocFx将生成的网站放置在根解决方案文件夹下的docs文件夹中。这将导致以下文件夹结构：

Solution+ App+ DocFx+ docs+ LibSolution.sln

您可以指示DocFx将生成的网站放置在您喜欢的任何文件夹中。

我们将其命名为docs文件夹，并将其放置在根解决方案文件夹下，因为GitHub Pages希望这样。

如果您使用github托管开源项目，并且想为您的项目提供一个不错的文档站点，则只需将文档站点放在根目录下的docs文件夹中并将该docs文件夹设置为发布源即可轻松实现用于GitHub Pages网站。

filterConfig.yml文件

如DocFx文档所述：

“过滤器配置文件为YAML格式。您可以通过提供过滤器配置文件并指定其路径来过滤掉不需要的API或属性。”

放置一个具有以下内容的filterConfig.yml：

apiRules:
- exclude:# inherited members from FormuidRegex: ^System\.Windows\.Forms\.Form\..*$type: Member
- exclude:# inherited members from ControluidRegex: ^System\.Windows\.Forms\.Control\..*$type: Member
- exclude:# mentioning types from System.* namespaceuidRegex: ^System\..*$type: Type
- exclude:# mentioning types from Microsoft.* namespaceuidRegex: ^Microsoft\..*$type: Type

注意：包含uidRegex和type条目的行应以两个空格开头。YAML语言使用空格缩进。

概念文档和TOC（目录）文件

DocFx接受Markdown文件，其中包含由用户编写的概念性文档。使用TOC（目录）YAML文件组织那些Markdown文件。

在DocFx文件夹下，添加带有所需内容的index.md文件。

这是我的DocFx文件夹：

DocFxdocfx.jsonindex.md.gitignorefilterConfig.ymltoc.yml

在DocFx文件夹中，创建一个Concepts子文件夹并添加以下文件夹和文件：

Concepts+ AdvancedAbstract.mdAdvanced.mdtoc.yml+ EasyAbstract.mdEasy.mdtoc.ymlAbstract.mdtoc.yml

您可以将所需的任何内容放置在这些Markdown文件中。通常，这些文件包含有关所引用API的使用的概念性概述。

关于TOC文件，您可以查阅相关的DocFx文档，其中指出：

“DocFX支持处理Markdown文件或概念性文件，以及YAML或JSON格式的结构化数据模型或Metadata文件。除此之外，DocFX引入了一种使用目录文件或TOC文件来组织这些文件的方法，以便用户可以浏览元数据文件和概念文件。”

下面列出了使用的三个toc.yml文件：

1、Concepts/toc.yml：

- name: Easyhref: Easy/toc.ymltopicHref: Easy/Abstract.md
- name: Advancedhref: Advanced/toc.ymltopicHref: Advanced/Abstract.md

2、Concepts/Advanced/toc.yml：

- name: Advanced Overview Titlehref: Advanced.md

3、Concepts/Easy/toc.yml：

- name: Easy Overview Titlehref: Easy.md

name条目是要单击的标题，即链接，将由生成的站点的目录显示。
href条目说明单击该标题时的导航位置。
可选的topicHref说明要显示的内容文件。当href链接到另一个toc.yml（即另一个目录）时使用，但用户希望向访问者提供某种关于它将在该链接中找到的内容的抽象。

.gitignore文件

docfx init -q命令在DocFx文件夹中添加一个.gitignore文件。创建具有以下内容的.gitignore文件，并将其放入DocFx文件夹中。

/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
reference

生成文档站点

为了生成网站，请打开终端，cd进入DocFx文件夹，然后键入：

docfx

网站已生成。

现在该预览该网站了。根据文档：

“如果未使用端口8080，则docfx将在http://localhost:8080下托管_site。如果正在使用8080，则可以使用docfx serve _site -p <port>更改由docfx使用的端口。”

要预览网站，请cd到docs：

cd ../docs

然后输入：

docfx serve

或者如果该端口8080是由另一个应用程序占用的，则只需使用另一个端口：

docfx serve -p 8081

现在，文档站点正在运行。

打开浏览器并导航到http://localhost:8080。

或者，如果将生成的站点的文件夹放在DocFx文件夹下，则可以只用一行就可以构建和运行该站点。

docfx --serve

您可以删除生成的文件夹，reference和docs。它们会在每个版本中重新创建。

将生成的文档站点发布到GitHub Pages

Push 您的本地git存储库到github远程存储库。
在github存储库中，转到“设置”（最右边带有齿轮图标）。
向下滚动到GitHub Pages部分。
选择master分支/ docs文件夹作为Source。
千万不要选择主题。

就这样。您的文档站点将很快通过以下网址提供：

`https://USER_NAME.github.io/PROJECT_NAME/`

PDF历险记

DocFx可以为整个生成的文档生成一个PDF文件。并非没有问题。

DocFx使用wkhtmltopdf工具生成PDF输出。

要下载并安装wkhtmltopdf，请以管理员身份打开终端并输入：

choco install wkhtmltopdf -y

为了生成令人垂涎的PDF文件，用户必须阅读并...理解DocFx提供的相关文档。

其中的一条信息可以在用户手册中找到，而另一条信息可以在第三个演练中找到。

经过大量的探索和试验，这是我的方法：

在DocFx文件夹中添加PDF文件夹
在PDF文件夹中添加以下toc.yml：

- name: Conceptshref: ../Concepts/toc.yml
- name: Referencehref: ../reference/toc.yml

在docfx.json中添加具有以下内容的pdf部分：

"pdf": {"content": [{"files": [ "PDF/toc.yml" ]},{"files": ["reference/**.yml","reference/index.md"],"exclude": ["**/toc.yml","**/toc.md"]},{"files": ["Concepts/**.md","Concepts/**/toc.yml","toc.yml","*.md"],"exclude": ["**/bin/**","**/obj/**","PDF/**","**/toc.yml","**/toc.md"]}],"resource": [{"files": [ "images/**" ],"exclude": ["**/bin/**","**/obj/**","PDF/**"]}],"dest": "_pdf","outline": "NoOutline"
}

打开一个终端，cd进入DocFx文件夹并输入：

docfx pdf

这将生成一个没有轮廓的PDF文件，即PDF TOC。显然存在问题，并且轮廓未正确生成。因此，我使用"outline": "NoOutline"停用了。

经过测试

Windows 10
docfx 2.48.1.0
wkhtmltopdf 0.12.5（带有修补的qt）

使用DocFx生成文档网站并将其发布到GitHub Pages相关推荐

docsify - 生成文档网站简单使用教程
1. docsify介绍 docsify 是一个动态生成文档网站的工具.不同于 GitBook.Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行. 这将非常 ...
使用DocFX生成文档
使用DocFX命令行生成文档使用docfx 命令 1.下载 https://github.com/dotnet/docfx/releases 2.使用创建初始项目 docfx init -q 此命 ...
docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档
为什么用 TypeScript? TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any ...
使用 apiDoc 为你的Node.js API 生成文档
翻译: 疯狂的技术宅原文:jonathas.com/documenting- 未经许可,禁止转载! 当你为其他开发人员(前端,桌面,移动等)开发 API 时,需要生成一份风格良好的文档,以便他们知道 ...
IDEA 版 API 接口神器来了，一键生成文档，嘎嘎香！
先看效果,这个文档就是通过该 IDEA 插件自动生成的,你能相信吗? 文档链接:https://petstore.apifox.cn 每个开发都不想写文档.当你不想写接口文档时,可以通过安装插件在 I ...
python+Xpath爬取英文新闻并生成文档词频矩阵
详情见我的github:https://github.com/Snowing-ST/Statistical-Case-Studies/tree/master/Lab3%20English%20Text ...
Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
Objective-C 自动生成文档工具:appledoc
来源:iOS_小松哥 www.jianshu.com/p/fd4d8d6b6177 如有好文章投稿,请点击 → 这里了解详情由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective ...
java前端目录_[Java教程]前端那点事儿——Tocify自动生成文档目录
[Java教程]前端那点事儿--Tocify自动生成文档目录 0 2016-06-29 22:00:07 今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目 ...

使用DocFx生成文档网站并将其发布到GitHub Pages

介绍

DocFx安装

Visual Studio中的测试解决方案

使用docfx init设置DocFx

手动设置DocFx

docfx.json配置文件的剖析

元数据部分

构建部分

docs文件夹

filterConfig.yml文件

概念文档和TOC（目录）文件

.gitignore文件

生成文档站点

将生成的文档站点发布到GitHub Pages

PDF历险记

经过测试

使用DocFx生成文档网站并将其发布到GitHub Pages相关推荐

最新文章

热门文章