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

引言

Github

• Github是一个托管网站，目前主要用来托管代码，当然托管其他的也可。但是需要科学上网，网不好的小伙伴可以考虑使用Gitee作为平替。

Sphinx

• Sphinx是什么? Sphinx是一个自动生成文档的工具，可以用简洁的语法快速生成优雅的文档。

• 哪些场景要用Sphinx? 如果想要写书，不想陷入复杂的排版中，可以考虑使用这个。如果有代码项目之类的，可以用它快速生成使用文档，支持markdown语法。

Readthedocs

• RTD(Read the docs) 是一个文档托管网站，这一点从网站名字上就能看出来。
• 在与Github连接上配置无误的情况下，当Github上有文件改动时，会自动触发RTD自动更新对应的文档。RTD提供了丰富的文档主题，有着灵活的配置，可以满足大部分的需求。
• RTD vs Github Pages：

  • Github Pages是Github下自带的静态网站托管服务，选择合适主题后，也可根据Github的内容，自动排版和更新对应内容到网站中。之前搭建过一个，感兴趣可以去AI比赛经验帖子集锦查看。下图是缩略图：

  • 选择RTD的理由是什么呢？ 对于我来说，有一点是最主要的：RTD可以做多版本文档的显示。当在Github仓库Release时，RTD网站也会出对应一版的文档，可以自己来选择是否激活。类似下图。而其他功能，两者都差不多。（仅一家之言）
    

部署前环境情况

• 自己的Github 代码仓库（本文以RapidVideOCR为例）
• 注册好的Read the docs账号，注册地址：注册

搭建步骤

Note：请静下心来，一步一步地来。

一、本地搭建Sphinx环境，用于本地查看效果

1. 克隆远程Github仓库到本地：git clone [email protected]:SWHL/RapidVideOCR.git
2. 安装python和pip（这个请自行百度，假设已经安装好）
3. 安装sphinx: pip install sphinx
4. 基于RaidVideOCR创建sphinx项目工程，命令执行情况如下：

   (demo) PS G:\ProgramFiles\_self\RapidVideOCR> sphinx-quickstart
   Welcome to the Sphinx 5.3.0 quickstart utility.
   
   Please enter values for the following settings (just press Enter to
   accept a default value, if one is given in brackets).
   
   Selected root path: .
   
   You have two options for placing the build directory for Sphinx output.
   Either, you use a directory "_build" within the root path, or you separate
   "source" and "build" directories within the root path.
   > Separate source and build directories (y/n) [n]: y
   
   The project name will occur in several places in the built documentation.
   > Project name: RapidVideOCR
   > Author name(s): SWHL
   > Project release []: v2.1.6
   
   If the documents are to be written in a language other than English,
   you can select a language here by its language code. Sphinx will then
   translate text that it generates into that language.
   
   For a list of supported codes, see
   https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
   > Project language [en]: zh_CN
   
   Creating file G:\ProgramFiles\_self\RapidVideOCR\source\conf.py.
   Creating file G:\ProgramFiles\_self\RapidVideOCR\source\index.rst.
   Creating file G:\ProgramFiles\_self\RapidVideOCR\Makefile.
   Creating file G:\ProgramFiles\_self\RapidVideOCR\make.bat.
   
   Finished: An initial directory structure has been created.
   
   You should now populate your master file G:\ProgramFiles\_self\RapidVideOCR\source\index.rst and create other documentation
   source files. Use the Makefile to build the docs, like so:
      make builder
   where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
   

5. 最终文件目录结构：

   RapidVideOCR
   ├── build  # 生成的文件的输出目录
   ├── LICENSE
   ├── make.bat  # Windows 命令行中编译用的脚本
   ├── Makefile  # 编译脚本，make 命令编译时用
   ├── rapid_videocr
   ├── README.md
   ├── requirements.txt
   ├── setup.py
   ├── source  # 存放文档源文件
   │   ├── conf.py  # 进行 Sphinx 的配置，如主题配置等
   │   ├── index.rst  # 文档项目起始文件，用于配置文档的显示结构
   │   ├── _static  # 静态文件目录，比如图片等
   │   └── _templates  # 模板目录
   └── tests
   

6. 生成最原始的文档文件:

    (demo) PS G:\ProgramFiles\_self\RapidVideOCR> make html
    Running Sphinx v5.3.0
    loading translations [zh_CN]... done
    making output directory... done
    building [mo]: targets for 0 po files that are out of date
    building [html]: targets for 1 source files that are out of date
    updating environment: [new config] 1 added, 0 changed, 0 removed
    reading sources... [100%] index
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] index
    generating indices... genindex done
    writing additional pages... search done
    copying static files... done
    copying extra files... done
    dumping search index in Chinese (code: zh)... done
    dumping object inventory... done
    build succeeded.
    
    The HTML pages are in build\html.
    (demo) PS G:\ProgramFiles\_self\RapidVideOCR> 
   

7. 查看效果
   • 打开RapidVideOCR目录下的build/html，双击打开index.html

     build
     ├── doctrees
     │   ├── environment.pickle
     │   └── index.doctree
     └── html
         ├── genindex.html
         ├── index.html  # 双击打开这个
         ├── objects.inv
         ├── search.html
         ├── searchindex.js
         ├── _sources
         └── _static
     

   • 效果如下图所示：
     

• 至此，本地最基本的Spinx文档系统搭建已经完成。

---

二、定制化部分

说明：定制化的配置都在source/conf.py中设置。因为有一些额外需求，因此需要定制化。

1. 更改样式主题。我这里以sphinx_rtd_theme为例子，其他主题可自行百度。

   • 安装sphinx_rtd_theme: pip install sphinx_rtd_theme

2. 安装markdown语法支持插件：pip install myst-parser

3. 安装支持mermaid渲染插件: pip install sphinxcontrib.mermaid

   ```{mermaid}  # 注意这里需要{}包裹
   graph LR
     a --> b
   ```
   

4. 安装代码块一键复制按钮插件：pip install sphinx_copybutton

5. 最后配置conf.py如下，

   project = 'RapidVideOCR'
   copyright = '2023, SWHL'
   author = 'SWHL'
   release = 'v2.1.6'
       
   extensions = [
       'myst_parser',
       "sphinxcontrib.mermaid",
       "sphinx_copybutton",
   ]
   
   source_suffix = {
         
         
       '.rst': 'restructuredtext',
       '.txt': 'markdown',
       '.md': 'markdown',
   }
   
   myst_enable_extensions = [
       "tasklist",
       "deflist",
       "dollarmath",
   ]
   
   templates_path = ['_templates']
   exclude_patterns = []
   
   language = 'zh_CN'
   
   html_theme = 'sphinx_rtd_theme'
   html_theme_options = {
         
         
       'analytics_anonymize_ip': False,
       'logo_only': True,
       'display_version': True,
       'prev_next_buttons_location': 'bottom',
       'style_external_links': False,
       'collapse_navigation': True,
       'sticky_navigation': True,
       'navigation_depth': 4,
       'includehidden': True,
       'titles_only': False,
   }
   
   html_logo = "./_static/logo.png"
   html_static_path = ['_static']
   html_js_files = [
       'my_custom.js',
   ]
   

6. my_custom.js写法（以下为示例）

   • 下面这段代码用来设置主题左上角logo的重定向到指定链接。my_custom.js位于_static目录下

     $(document).ready(function(){
             
             
         let div_logo = document.getElementsByClassName("wy-side-nav-search")[0];
         let a_logo = div_logo.getElementsByTagName("a");
         a_logo[0].href = "https://github.com/SWHL/RapidVideOCR";
         a_logo[0].target = "_blank";
     });
     

7. 重新生成html，查看效果

   • 执行make html

     (demo) PS G:\ProgramFiles\_self\RapidVideOCR> make html
     Running Sphinx v5.3.0
     loading translations [zh_CN]... done
     loading pickled environment... done
     myst v0.18.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=['tasklist', 'deflist', 'dollarmath'], disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, highlight_code_blocks=True, number_code_blocks=[], title_to_header=False, heading_anchors=None, heading_slug_func=None, footnote_transition=True, words_per_minute=200, sub_delimiters=('{', '}'), linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area')
     building [mo]: targets for 0 po files that are out of date
     building [html]: targets for 1 source files that are out of date
     updating environment: 0 added, 0 changed, 0 removed
     looking for now-outdated files... none found
     preparing documents... done
     writing output... [100%] index
     generating indices... genindex done
     writing additional pages... search done
     copying static files... done
     copying extra files... done
     dumping search index in Chinese (code: zh)... done
     dumping object inventory... done
     build succeeded.
     
     The HTML pages are in build\html.
     (demo) PS G:\ProgramFiles\_self\RapidVideOCR>
     

   • 打开build/html/index.html查看效果

• 至此，简单的定制化已经完毕。接下来就是要在文档中插入内容和部署到Read the docs网站了。

继续阅读

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