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

1|0引言

1|1Github

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

1|2Sphinx

Sphinx是什么? Sphinx是一个自动生成文档的工具，可以用简洁的语法快速生成优雅的文档。
哪些场景要用Sphinx? 如果想要写书，不想陷入复杂的排版中，可以考虑使用这个。如果有代码项目之类的，可以用它快速生成使用文档，支持markdown语法。

1|3Readthedocs

RTD(Read the docs) 是一个文档托管网站，这一点从网站名字上就能看出来。
在与Github连接上配置无误的情况下，当Github上有文件改动时，会自动触发RTD自动更新对应的文档。RTD提供了丰富的文档主题，有着灵活的配置，可以满足大部分的需求。
RTD vs Github Pages：
- Github Pages是Github下自带的静态网站托管服务，选择合适主题后，也可根据Github的内容，自动排版和更新对应内容到网站中。之前搭建过一个，感兴趣可以去AI比赛经验帖子集锦。下图是缩略图： !
- 选择RTD的理由是什么呢？ 对于我来说，有一点是最主要的：RTD可以做多版本文档的显示。当在Github仓库Release时，RTD网站也会出对应一版的文档，可以自己来选择是否激活。类似下图。而其他功能，两者都差不多。（仅一家之言）

2|0部署前环境情况

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

3|0搭建步骤

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

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

克隆远程Github仓库到本地：git clone git@github.com:SWHL/RapidVideOCR.git
安装python和pip（这个请自行百度，假设已经安装好）
安装sphinx: pip install sphinx

基于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.

最终文件目录结构：

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

生成最原始的文档文件:

 (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>

查看效果

打开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文档系统搭建已经完成。

3|2二、定制化部分

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

更改样式主题。我这里以sphinx_rtd_theme为例子，其他主题可自行百度。
- 安装sphinx_rtd_theme: pip install sphinx_rtd_theme
安装markdown语法支持插件：pip install myst-parser

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

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

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

最后配置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',
]

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";
});

重新生成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查看效果

至此，简单的定制化已经完毕。

4|0继续阅读

__EOF__

本文作者：Danno
本文链接：https://www.cnblogs.com/shiwanghualuo/p/17280590.html
关于博主：评论和私信会在第一时间回复。或者直接私信我。
版权声明：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
声援博主：如果您觉得文章对您有帮助，可以点击文章右下角【推荐】一下。您的鼓励是博主的最大动力！