使用DocFX制作文档&&利用Github Actions自动部署到Github Pages

前言

笔者维护的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将他们组织起来，如：

- 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

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/checkout@v2.3.1
        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/checkout@v2.3.1
        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里即可。