docfx 简单使用方法、自动生成目录的工具

内容纲要

[摘要]

这是我编写的一个 Docfx 文档自动生成工具,只要写好 Markdown 文档,使用此工具可为目录、文件快速生成配置,然后直接使用 docfx 运行即可。

https://github.com/whuanle/CZGL.DocfxBuild.Yml/releases/tag/1.0

一,安装Docfx

下载地址 https://github.com/dotnet/docfx/releases

下载后解压压缩包,记录好目录路径。

Win 搜索 “环境变量”,会出现 “编辑系统环境变量”。

然后 ↓

《docfx 简单使用方法、自动生成目录的工具》

新建一个目录,用来存放 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 docfx_project\docfx.json --serve

预览

《docfx 简单使用方法、自动生成目录的工具》

对于 项目,可以快速生成对象文档、代码文档。

这里有关于 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

《docfx 简单使用方法、自动生成目录的工具》

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

效果预览 https://doc.whuanle.cn

晚上有事,今天的博客水完了。

点赞
  1. kamagra prices说道:

    Needed to write you this very small word to help thank you very much yet again with the superb tricks you have shown on this website. This is so unbelievably open-handed with you to provide without restraint what exactly numerous people would have supplied for an electronic book to make some profit on their own, principally since you might well have tried it in the event you wanted. Those thoughts likewise worked to provide a great way to understand that the rest have the same zeal the same as my very own to understand way more with regards to this problem. I think there are thousands of more pleasurable times up front for those who take a look at your website.

  2. propecia buy说道:

    Thank you for your entire labor on this web site. My mom take interest in managing investigations and it is obvious why. My partner and i learn all regarding the lively tactic you produce simple things through your web site and in addition invigorate response from the others on the situation then our favorite princess is truly studying a whole lot. Take advantage of the rest of the year. You have been doing a superb job.

发表评论

邮箱地址不会被公开。 必填项已用*标注

You must enable javascript to see captcha here!