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

引言

• 接上一篇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 git@github.com:SWHL/RapidVideOCR.git

   xxx@xxx MINGW64 /g/ProgramFiles/_self/tmp
   $ git clone git@github.com: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）

   

布置到Read the docs网站

• 现在Sphinx烘托的文件已经保管到Github的docs分支，接下来需求保管到Read the docs网站，便于咱们检查和访问。

1. 注册或登录 Raad the docs
2. 连接Github服务。

   

3. 点击导入一个项目按钮

   

4. 选择RapidVideOCR项目

   

5. 注意更改默许分支为docs, 点击下一页即可

   

6. 点击Build version，即可开始构建文档

   

7. 等成功之后，点击右上角的阅览文档，即可检查。

   

• 至此，整个Sphinx烘托的内容已经成功布置到Read the docs网站了。

持续阅览

• Github + Sphinx+Read the docs 实战入门攻略（一）
• Github + Sphinx+Read the docs 实战入门攻略（三）