前言
笔者维护的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,所以是没有现成的办法了,但是我们知道大概的发布流程:
- 获取master
- 安装docfx
- 生成docs
- 获取gh-pages
- 更新gh-pages
- 提交、推送
基于此,经过两天调试。我完成如下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 jobs: build-and-deploy: runs-on: windows-latest steps: - name: Checkout master uses: actions/[email protected] with: ref: master path: master
- name: Install docfx run: choco install docfx -y - name: docfx build run: docfx docfx.json working-directory: master - name: Checkout docs uses: actions/[email protected] with: ref: gh-pages path: gh-pages - name: Clear docs run: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ } working-directory: gh-pages - name: Sync new content 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里即可。