前言

笔者维护的MobileSuit项目在七月进行了一次大更新,但是由于懒一直也没有更新文档。在开学初,终于下定决心,对文档进行更新。

在之前,文档一直采用的是基于hexo的主题的一个文档模板,这个东西bug很多,用起来也很不方便。之前,了解到DocFX是专为C#设计的文档生成器,所以进行了安装和试用。

DocFX的使用

安装DocFX

DocFX只支持Windows平台。可以直接下载压缩包,也可以从巧克力安装DocFX,但是不能从winget安装(离谱)。

初始化

在项目目录处执行docfx init即可进行初始化配置。一般的,保持默认就好了(所以说其实可以直接docfx init -q),但是我把其中的生成目标目录 _site 改成了 docs

之后,docfx在项目目录下生成了子目录docfx_project,推荐直接把里面的内容复制到项目根目录。

开始写文档

api这个文件夹里存api文档,我们需要手动写的只有index.md一个文件;其他的会根据你项目的xml注释自动生成,非常方便。
articles里存放的是你自己写的文档,你需要写各种md,然后用toc.yml将他们组织起来,如:

1
2
3
4
5
6
7
8
9
10
- name: Introduction
href: intro.md
- name: Get Started
href: GetStarted.md
- name: Create CommandLine Applications
href: CreateCommandLineApplication.md
- name: Use Special Parameters
href: UseSpecialParameters.md
- name: Customization
href: Customization.md

之后,修改根目录下的index.md和toc.yml即可。

预览网站

运行docfx docfx.json即可生成网站,但是如果我们运行docfx docfx.json --serve就可以直接生成并运行预览。预览满意之后,可以进入下一步:发布

使用持续集成服务发布到Github Pages

因为JamesIves/github-pages-deploy-action只支持Ubuntu环境,而docfx只支持windows,所以是没有现成的办法了,但是我们知道大概的发布流程:

  1. 获取master
  2. 安装docfx
  3. 生成docs
  4. 获取gh-pages
  5. 更新gh-pages
  6. 提交、推送

基于此,经过两天调试。我完成如下CI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
name: deploy_documentation
on:
push:
branches:
- master # Default release branch
jobs:
build-and-deploy:
runs-on: windows-latest
steps:
- name: Checkout master #获取master,放在master目录下
uses: actions/[email protected]
with:
ref: master
path: master

- name: Install docfx #安装docfx
run: choco install docfx -y
- name: docfx build #生成文档,这里会输出到master/docs,如果你采用默认的docfx设置,就是master/_site
run: docfx docfx.json
working-directory: master
- name: Checkout docs #获取gh-pages,如果没有这个分支,需要手动创建一下
uses: actions/[email protected]
with:
ref: gh-pages
path: gh-pages
- name: Clear docs #清空gh-pages中的内容
run: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ }
working-directory: gh-pages
- name: Sync new content #复制生成的docs到gh-pages
run: Copy-Item -Recurse -Verbose -Force "$env:GITHUB_WORKSPACE/master/docs/*" "$env:GITHUB_WORKSPACE/gh-pages"
working-directory: gh-pages
- name: Commit to gh-pages and push #提交推送
run: |
$ErrorActionPreference = "Continue"
git add -A
git diff HEAD --exit-code
if ($LASTEXITCODE -eq 0) {
Write-Host "No changes to commit!"
} else {
git config --global user.name "github-actions-docfx[bot]"
git config --global user.email "这里改成自己的邮箱"
git commit -m "Updated docs from commit $env:GITHUB_SHA on $env:GITHUB_REF"
git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_DOC }}@github.com/${{ github.repository }}
git push origin gh-pages
}
working-directory: gh-pages

其中,DEPLOY_DOC是一个personal token,自己到设置里生成一个加在仓库的secrets里即可。