[摘要]
这是我编写的一个 Docfx 文档自动生成工具,只要写好 Markdown 文档,使用此工具可为目录、文件快速生成配置,然后直接使用 docfx 运行即可。
https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0
一,安装Docfx
下载地址 https://github.com/dotnet/docfx/releases
下载后解压压缩包,记录好目录路径。
Win 搜索 “环境变量”,会出现 “编辑系统环境变量”。
然后 ↓
新建一个目录,用来存放 markdown 文件。打开目录,按住 Shift + 鼠标右键 ,打开 Powershell 。
两个命令
docfx init -q
docfx docfx_project\docfx.json --serve // 以实际路径为准
二, 创建 Docfx 项目
使用此命令在目录下初始一个 docfx 项目
docfx init -q
-q 这个参数表示忽略询问,直接生成。如果需要自定义配置,可取消 -q 这个参数。
打开 docfx_project 文件夹,目录结构如下:
docfx_project
.
├── api
│ ├── index.md
│ └── toc.yml
├── apidoc
├── articles
│ ├── intro.md
│ └── toc.yml
├── docfx.json
├── images
├── index.md
├── src
└── toc.yml
为代码创建 API 文档
src 目录用来存放你需要生成文档的项目,直接把整个项目(解决方案)放进去即可。
生成文档
docfx docfx_project\docfx.json --serve
预览
对于 项目,可以快速生成对象文档、代码文档。
这里有关于 REST API 生成文档的详细方法
https://dotnet.github.io/docfx/tutorial/intro_rest_api_documentation.html
三, 文字文档
文字文档使用 markdown 文件编写,存放位置 articles 。
├── intro.md
└── toc.yml
这两个文件是默认的, toc.yml 由于默认生成目录结构,intro.md 是打开文档是默认看到的,可以理解为封面内容。例如 Github 仓库的 Readme.md 。
为了生成多级目录,建议每个目录有应该有一个 toc.yml 文件。
最简单的语法
- name: xxx
href: xxxx
用于生成目录结构详细、文档文件,href 可以是 目录、 .md 文件、.yml 文件。
但 href 为 .yml 是,会生成目录结构。
使用
items:
- name: Topic2_1
href: Topic2_1.md
...
...
也可以生成层次结构。
homepage: index.md
用来生成首页文件,对于子目录,用处不大。
用来测试的文件和目录
.
└── articles
├── a
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── b
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── c
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── d
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ └── d.md
├── intro.md
└── toc.yml
使用 CZGL.DocfxBuild.Yml 自动生成后
.
└── articles
├── a
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── b
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── c
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── d
│ ├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── intro.md
└── toc.yml
生成文档:
docfx docfx_project\docfx.json --serve
使用 CZGL.DocfxBuild.Yml 可以帮助你快速生成文档目录。
根目录的 toc.yml 文件:
- name: a
href: a/toc.yml
- name: b
href: b/toc.yml
- name: c
href: c/toc.yml
- name: d
href: d/toc.yml
- name: intro
href: intro.md
homepage: intro.md
name 为目录名称。
href 指向子目录下的 toc.yml 文件
目录 a 的结构
.
├── a
│ ├── a.md
│ ├── b
│ ├── b.md
│ ├── c
│ ├── c.md
│ ├── d
│ ├── d.md
│ └── toc.yml
├── a.md
├── b
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── b.md
├── c
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── c.md
├── d
│ ├── a.md
│ ├── b.md
│ ├── c.md
│ ├── d.md
│ └── toc.yml
├── d.md
└── toc.yml
### G:\临时缓存\docfx\docfx_project\articles\a
- name: a
href: a/toc.yml
- name: b
href: b/toc.yml
- name: c
href: c/toc.yml
- name: d
href: d/toc.yml
- name: a
href: a.md
- name: b
href: b.md
- name: c
href: c.md
- name: d
href: d.md
homepage: a.md
每个目录一个 .yml 文件
如果这个目录下有目录,则连接子目录的 .yml 文件,如果是子文件,则链接这个 .md 文件。
这样能够快速生成文档目录。
当然也可以尝试 items
官方详细文档地址
https://dotnet.github.io/docfx/tutorial/intro_toc.html
利用空闲时间写了自动生成 docfx 目录的功能,下载地址
https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0
晚上有事,今天的博客水完了。