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文档中。

主要流程图

提交

Actions

文档更改

main分支

编译，产生html，提交到docs分支

RTD自动编译，更新文档

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

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

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

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: [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"
   

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

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

写在最后

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

继续阅读

• Github + Sphinx+Read the docs 实战入门指南(一)
• Github + Sphinx+Read the docs 实战入门指南(二)

其他相关资料：

• sphinx-apidoc 官方文档
• sphinx-rtd-theme 配置 官方文档