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

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

时间:2023-04-02 15:48:19浏览次数:54  
标签:RapidVideOCR 00 Github Sphinx Read docs rm

引言

  • 接上一篇Github + Sphinx+Read the docs 实战入门指南(一),这一篇主要讲解如何自动将指定文档内容部署到Read the docs中。
  • 对于文档,一般有以下基本要求:
    • 只维护一份,其他地方自动同步更新
    • 可以根据代码注释,动态更新维护相应的API文档
    • 支持检索
    • 多版本之间的API接口动态查看
  • 经过一段时间的调研和比较汇总,最终确定了以下技术方案:flowchart LR A("Github(托管代码和文档)") --> B("Sphinx(渲染文档)") --> C("Read the docs(托管Sphinx渲染的文档)")

Sphinx渲染文档托管到Github

  • 经过上一篇博客后,大家可以本地生成Sphinx渲染之后得到的html文档,但是只能本地查看。我们需要将其托管到Github中,便于后续Read the docs部署。
  • 下面我将以RapidVideOCR为例,讲解具体做法:
  1. 克隆RapidVideOCR项目到本地:git clone [email protected]:SWHL/RapidVideOCR.git
    xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp
    $ git clone [email protected]:SWHL/RapidVideOCR.git
    Cloning into 'RapidVideOCR'...
    remote: Enumerating objects: 1703, done.
    remote: Counting objects: 100% (262/262), done.
    remote: Compressing objects: 100% (183/183), done.
    remote: Total 1703 (delta 150), reused 177 (delta 77), pack-reused 1441
    Receiving objects: 100% (1703/1703), 12.01 MiB | 334.00 KiB/s, done.
    Resolving deltas: 100% (1011/1011), done.
    
  2. 新建一个空分支,名称为docs,用来部署Sphinx渲染之后的文件
    xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp
    $ cd RapidVideOCR/
    
    xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp/RapidVideOCR (main)
    $ git checkout --orphan docs
    Switched to a new branch 'docs'
    
    xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp/RapidVideOCR (docs)
    $ git rm -rf .
    rm '.github/FUNDING.yml'
    rm '.github/ISSUE_TEMPLATE/bug_report.md'
    rm '.github/ISSUE_TEMPLATE/feature_request.md'
    rm '.github/workflows/AutoPushToPypi.yml'
    rm '.github/workflows/SyncToGitee.yml'
    rm '.github/workflows/deploy_docs_to_rtd.yml'
    rm '.gitignore'
    rm 'LICENSE'
    rm 'README.md'
    rm 'assets/colab-badge.svg'
    rm 'assets/logo.png'
    rm 'demo.py'
    rm 'docs/FAQ.md'
    rm 'docs/README_en.md'
    rm 'docs/change_log.md'
    rm 'docs/change_log_en.md'
    rm 'docs/doc_whl.md'
    rm 'rapid_videocr/__init__.py'
    rm 'rapid_videocr/rapid_videocr.py'
    rm 'rapid_videocr/utils.py'
    rm 'requirements.txt'
    rm 'setup.py'
    rm 'tests/test_files/RGBImages/0_00_00_041__0_00_00_415_0070000000019200080001920.jpeg'
    rm 'tests/test_files/RGBImages/0_00_00_416__0_00_01_165_0070000000019200080001920.jpeg'
    rm 'tests/test_files/RGBImages/0_00_01_166__0_00_01_540_0070000000019200080001920.jpeg'
    rm 'tests/test_files/RGBImages/0_00_01_541__0_00_02_540_0070000000019200080001920.jpeg'
    rm 'tests/test_files/TXTImages/0_00_00_041__0_00_00_415_0070000000019200080001920.jpeg'
    rm 'tests/test_files/TXTImages/0_00_00_416__0_00_01_165_0070000000019200080001920.jpeg'
    rm 'tests/test_files/TXTImages/0_00_01_166__0_00_01_540_0070000000019200080001920.jpeg'
    rm 'tests/test_files/TXTImages/0_00_01_541__0_00_02_540_0070000000019200080001920.jpeg'
    rm 'tests/test_rapid_videocr.py'
    
    xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp/RapidVideOCR (docs)
    
  3. 将在上一篇博客中,本地运行Sphinx渲染之后的文件,拷贝到新的docs分支,具体文件包括如下:(详情可以参见RapidVideOCR docs
    RapidVideOCR
        ├── LICENSE
        ├── make.bat
        ├── Makefile
        ├── rapid_videocr
        │   ├── __init__.py
        │   ├── rapid_videocr.py
        │   └── utils.py
        ├── requirements.txt
        └── source
            ├── API
            ├── conf.py
            ├── index.rst
            ├── README.md
            └── _static
    
    • 其中source/API目录为sphinx-apidoc自动生成。
  4. 将上述新添加的文件提交到远程仓库
    $ git add .
    $ git commit -m 'Init commit'
    $ git push -u origin docs
    
  5. 去Github界面查看,示例图如下:(详情参见:RapidVideOCR docs
    image.png

部署到Read the docs网站

  • 目前Sphinx渲染的文件已经托管到Github的docs分支,接下来需要托管到Read the docs网站,便于大家查看和访问。
  1. 注册或登录 Raad the docs
  2. 连接Github服务。
    image.png
  3. 点击导入一个项目按钮
    image.png
  4. 选择RapidVideOCR项目
    image.png
  5. 注意更改默认分支为docs, 点击下一页即可
    image.png
  6. 点击Build version,即可开始构建文档
    image.png
  7. 等成功之后,点击右上角的阅读文档,即可查看。
    image.png
  • 至此,整个Sphinx渲染的内容已经成功部署到Read the docs网站了。

继续阅读

标签:RapidVideOCR,00,Github,Sphinx,Read,docs,rm
From: https://www.cnblogs.com/shiwanghualuo/p/17280584.html

相关文章

  • Github + Sphinx+Read the docs 实战入门指南(三)
    引言接着上两篇文章Github+Sphinx+Readthedocs实战入门指南(一)Github+Sphinx+Readthedocs实战入门指南(二)我们已经成功地将Sphinx文档部署到了Readthedocs网站,但是这个文档,我们不想每次都要手动更新内容,想要的是:在更改仓库主分支时,自动将相关内容更新部署......
  • 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.......