引言
- 接着上两篇文章
- 我们已经成功地将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为例,大家可以参照更改为自己的。
-
在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]