引言
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环境,用于本地查看效果
- 克隆远程Github仓库到本地:
git clone [email protected]: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
- 效果如下图所示:
- 打开RapidVideOCR目录下的build/html,双击打开index.html
- 至此,本地最基本的Spinx文档系统搭建已经完成。
二、定制化部分
说明:定制化的配置都在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"; });
- 下面这段代码用来设置主题左上角logo的重定向到指定链接。
-
重新生成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查看效果
- 执行
- 至此,简单的定制化已经完毕。