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

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

主要流程图

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

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

在main分支下创建自己的Actions，参考下图：

创建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: [email protected]: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"

提交之后，就会自动触发Actions执行，详细状态可以看下图红框位置：
RTD中文档编译状态，可在RTD项目主页中查看。（详情请戳RTD dashboard）

写在最后

经过三篇系列文章，只能算是基本上把Github + Sphinx + Read the docs系列说清楚了。这中间过程中有许多细节需要大家注意，我这里并不能面面俱到，希望大家谅解。
大家在实践过程中，如遇到具体问题，欢迎交流讨论。邮箱：[email protected]

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

目录

引言

主要流程图

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

写在最后

继续阅读

其他相关资料：

猜你喜欢