首页 > 其他分享 >Github + Sphinx+Read the docs 实战入门指南(三)

Github + Sphinx+Read the docs 实战入门指南(三)

时间:2023-04-02 15:47:11浏览次数:52  
标签:Github Sphinx Read docs echo git

引言

  • 接着上两篇文章
  • 我们已经成功地将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,参考下图:
    image.png

  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执行,详细状态可以看下图红框位置:
    image.png

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

写在最后

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

继续阅读

标签:Github,Sphinx,Read,docs,echo,git
From: https://www.cnblogs.com/shiwanghualuo/p/17280586.html

相关文章

  • Github + Sphinx+Read the docs 实战入门指南(一)
    引言GithubGithub是一个托管网站,目前主要用来托管代码,当然托管其他的也可。但是网不好的小伙伴可以考虑使用Gitee作为平替。SphinxSphinx是什么?Sphinx是一个自动生成文档的工具,可以用简洁的语法快速生成优雅的文档。哪些场景要用Sphinx?如果想要写书,不想陷入复杂的......
  • 【webpack】TypeError: Cannot read property 'tap' of undefined
    前言项目里使用webpack的代码混淆工具webpack-obfuscator,当打包代码时,出现如下报错:TypeError:Cannotreadproperty'tap'ofundefined原因项目的webpack版是4.x,而webpack-obfuscator的版本是3.x解决方法查阅资料在该https://nodejs7.com/2021/11/27/797.html文......
  • ESPRESSIF-pip安装模板超时Read timed out
    一、问题:pip._vendor.urllib3.exceptions.ReadTimeoutError:HTTPSConnectionPool(host='files.pythonhosted.org',port=443):Readtimedout.Commandfailed:"C:\Users\zhang\.espressif\python_env\idf4.4_py3.8_env\Scripts\python.exe"-mp......
  • 类型类Type classes(第一部分)类约束 Eq、Ord、Show、Read、Enum、Num、Integral、Float
    类型类Typeclasses是一种定义某种行为的接口。如果类型是类型类的成员,则意味着类型支持并实现了类型类定义的行为。类约束==函数的类型,如下:type(==)(==)::Eqa=>a->a->Bool=>符号定义了一个类约束,==函数接受两个相同类型的形参,并返回Bool类型。这两个形参的类型......
  • AI写代码 GitHub Copilot + Idea 安装和使用教程
    GitHubCopilot是微软与OpenAI共同推出的一款AI编程工具,基于GitHub及其他网站的源代码,根据上文提示为程序员自动编写下文代码,可以极大地提高编写代码的效率。根据已有上下文补全代码根据函数名和参数,生成方法体根据注释自动生成代码代码优化生成测试代码一、GitHubCopil......
  • Visual Studio Code 1.77 发布,扩展的 GitHub Copilot 集成
    VSCode1.77已发布,此版本一些主要亮点包括:Accessibility改进 -用于悬停、通知和StickyScroll的新键盘快捷键。、down、home、end、pageup和pagedown 键来聚焦悬停控件并进行水平和垂直滚动。聚焦悬停控件的键盘快捷键(Ctrl+KCtrl+I)与用于在主光标位置显示悬停的......
  • GitHub OAuth 第三方登录示例
     ⇐  ⇒GitHubOAuth第三方登录示例教程作者:阮一峰日期:2019年4月21日这组OAuth系列教程,第一篇介绍了基本概念,第二篇介绍了获取令牌的四种方式,今天演示一个实例,如何通过OAuth获取API数据。很多网站登录时,允许使用第三方网站的身份,这称为"第三......
  • c++ 多线程编程std::thread, std::shared_mutex, std::unique_lock
    在C++11新标准中,可以简单通过使用thread库,来管理多线程,使用时需要#include<thread>头文件。简单用例如下:1std::thread(Simple_func);2std::threadt(Simple_func);3t.detach();第一行是直接启动一个新线程来执行Simple_func函数,而第二行先声明一个线程函数t(返回类型为......
  • README
    pytestcachedirectoryThisdirectorycontainsdatafromthepytest'scacheplugin,whichprovidesthe--lfand--ffoptions,aswellasthecachefixture.Donotcommitthistoversioncontrol.Seethedocsformoreinformation.......
  • 线程池----ThreadPoolExecutor
    从Java5开始,Java提供了自己的线程池。线程池就是一个线程的容器,每次只执行额定数量的线程。java.util.concurrent.ThreadPoolExecutor就是这样的线程池。它很灵活,但使用起来也比较复杂,本文就对其做一个介绍。首先是构造函数。以最简单的构造函数为例:publicThreadPoolExecuto......