引言

  • 接着上两篇文章
    • Github + Sphinx+Read the docs 实战入门攻略(一)
    • Github + Sphinx+Read the docs 实战入门攻略(二)
  • 咱们现已成功地将Sphinx文档部署到了Read the docs网站，但是这个文档，咱们不想每次都要手动更新内容，想要的是：在更改库房主分支时，主动将相关内容更新部署到Read the docs中。
  • 经过调研，挑选Github Actions来主动完结这个使命。
  • 目前RapidVideOCR中整个文档系统现已搭建完结，感兴趣的小伙伴可以前去观看。我只需求正常更新主分支的代码和文档，后续会主动更新到Read the docs文档中。

主要流程图

flowchart LR
A(文档更改) --提交--> B(main分支) --Actions--> C("编译，发生html，提交到docs分支") --> E("RTD主动编译，更新文档")

主动更新主分支内容到docs分支

  • 这一步用Github Actions来完结，关于Github Actions，感兴趣的小伙伴可以主动百度学习，我这儿就不再打开赘述。
  • 下面依旧以RapidVideOCR为例，我们可以参照更改为自己的。

  1. 在main分支下创立自己的Actions，参考下图：

    Github + Sphinx+Read the docs 实战入门指南（三）

  2. 创立deploy_docs_to_rtd.yml文件，张贴如下代码并提交：(详情参见deploy_docs_to_rtd.yml)

    name: Deploy the docs to RTD
on:
  push:
    branches: [ main ]
    paths:  # 当更改以下文件时，会触发Actions更新文档
      - 'rapid_videocr/**'
      - '.github/workflows/deploy_docs_to_rtd.yml'
      - 'README.md'
env:
  REPO_SSH: git@github.com:SWHL/RapidVideOCR.git
  CLONE_URL: ${{ github.event.repository.clone_url }}
  USER_NAME: ${{ github.event.repository.owner.name }}
  USER_EMAIL: ${{ github.event.repository.owner.email }}
  SUBMMIT_BRANCH: docs
  PACKAGE_NAME: rapid_videocr
jobs:
  Deploy_TO_RTD:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python 3.7
        uses: actions/setup-python@v4
        with:
          python-version: '3.7'
          architecture: 'x64'
      - name: Set SSH Environment
        env:
          DEPLOY_KEYS: ${{ secrets.DEPLOY_KEYS }}
        run: |
          mkdir -p ~/.ssh/
          echo "$DEPLOY_KEYS" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          chmod 700 ~/.ssh && chmod 600 ~/.ssh/*
          git config --global user.name $USER_NAME
          git config --global user.email $USER_EMAIL

      - name: Summit repo to docs branch.
        run: |
          ls
          rm -r docs

          git clone -b ${SUBMMIT_BRANCH} $CLONE_URL ${SUBMMIT_BRANCH}
          cd ${SUBMMIT_BRANCH}
          rm -r ${PACKAGE_NAME} || true
          rm source/README.md || true
          echo "====================="
          echo ${SUBMMIT_BRANCH}
          cp -r ../${PACKAGE_NAME} .
          echo "Update requirements and add packages needed by sphinx"
          echo -e '\nsphinx_rtd_theme\nsphinxcontrib.mermaid\nmyst-parser\nsphinx_copybutton\nget_pypi_latest_version' >> ../requirements.txt
          rm requirements.txt
          cp ../requirements.txt .
          echo "replace mermaid to {mermaid}"
          sed -i 's/mermaid/{mermaid}/g' ../README.md
          cp ../README.md source/
          echo "Generate the api doc"
          pip install sphinx
          sphinx-apidoc -o source/API/ ./${PACKAGE_NAME} -f -E -M
          sed -i '1d' source/API/modules.rst
          sed -i '1i\API' source/API/modules.rst
          git add .
          git status
          git remote remove origin
          git remote add origin ${REPO_SSH}
          git commit -m 'Actions auto update' && git push -f origin ${SUBMMIT_BRANCH} || echo "No changes to commit"

  3. 提交之后，就会主动触发Actions执行，详细状况可以看下图红框方位：

    Github + Sphinx+Read the docs 实战入门指南（三）

  4. RTD中文档编译状况，可在RTD项目主页中查看。（详情请戳RTD dashboard）

写在最终

  • 经过三篇系列文章，只能算是基本上把Github + Sphinx + Read the docs系列说清楚了。这中间进程中有许多细节需求我们注意，我这儿并不能八面玲珑，期望我们体谅。
  • 我们在实践进程中，如遇到具体问题，欢迎沟通讨论。邮箱：liekkaskono@163.com

持续阅读

  • Github + Sphinx+Read the docs 实战入门攻略（一）
  • Github + Sphinx+Read the docs 实战入门攻略（二）

其他相关资料：

  • sphinx-apidoc 官方文档
  • sphinx-rtd-theme 装备 官方文档