跳转至

使用Sphinx搭建文档库

本文创建时间: 2022.05.05 22:06:29，更新时间: 2022.07.17 23:02:41

基于sphinx构建文档库

配置Python环境

安装Python3环境

建议版本3.8+，具体过程略

安装依赖

依赖包，即 requirements.txt

Bash
1
2
3
4
sphinx
sphinx-autobuild
sphinx_rtd_theme
myst-parser
安装依赖
Bash
1
pip install -r requirements.txt

配置sphinx

快速初始化

Bash
1
sphinx-quickstart

执行完毕操作后，可以生成sphinx文档的基本框架，其中conf.py是配置文件，下面直接修改文件如下以满足要求

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 项目信息
project = 'LZWANG-LIB'
copyright = '2022, lzwang'
author = 'lzwang'

# 文档版本号
release = 'alpha 0.1'

# 文档语言
language = 'zh_CN'

# html渲染主题
html_theme = 'sphinx_rtd_theme'

# sphinx扩展插件列表
extensions = ['myst_parser']

# 模板目录
templates_path = ['_templates']

# 额外的静态文件目录
html_static_path = ['_static']

# 忽略的文件
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# 源码文件匹配
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

# 文档生成后的入口文件
root_doc = 'index'

sphinx基本使用

新增文章

如果要在./source目录下增加一篇新的文章hello-world.md，那么在index.rst文件中作出如下更改

Text Only
1
2
3
4
5
6
7
.. toctree::
   :maxdepth: 2
   :caption: 目录:

   source/hello
   source/hello-world  # 新增
   ./readme

注意sphinx根据上面文件的顺序生成html的文章顺序

生成静态网页

生成html静态文件

Bash
1
make html

注意纯静态文件需要额外的http服务才能被访问

启动http服务

自动检测文件变动，启动http服务并实时构建html

Bash
1
sphinx-autobuild . _build/html

默认在http://127.0.0.1:8000打开预览

利用MyST Parser插件，实现Markdown渲染

Markdown基本语法可参考: Basic Syntax | Markdown Guide
下面是一些强化的Markdown功能，有些需要额外的插件，这些功能可以使生成的文档更具有表现力

Admonition扩展

MyST Parser自带，无需额外插件，示例代码如下:

Text Only
1
2
3
:class: warning

这是一段`warning`文本

Mermaid扩展

首先安装额外的pip包

Bash
1
pip install sphinxcontrib-mermaid
需要安装额外的插件，在sphinx的conf.py中，更改
Python
1
2
3
4
extensions = [
  "myst_parser",
  "sphinxcontrib.mermaid",
]

效果见 Get started with MyST in Sphinx

参考资料