Shpinx 在 Windows 下的操作记录

排版约定

以下内容中的代码块有 > 提示符的行，均为在 Powershell 中执行的命令。

相关资源

• Sphinx 官网
• Sphinx 中文文档
• Sphinx 主题
• sphinx-rtd-theme
• Pandoc

Python 安装

Windows 10 安装 Python 3.8，采用安装向导提供的推荐选项安装即可。

设置国内 Pypi 源

运行 Powershell 终端：执行以下两条命令，第一条是升级 pip，第二条是将 pip 的默认软件源修改为国内的镜像。

> pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pip -U
> pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

注意 > 为终端命令提示符，不是命令。

安装 Shpinx

> pip install -U Sphinx

初始化文档结构

> sphinx-quickstart.exe

编译

在项目根目录执行

> .\make.bat html

配置 sphinx-rtd-theme 主题

安装主题

> pip install sphinx-rtd-theme

编辑 conf.py 添加：

import sphinx_rtd_theme

extensions = [
    ...
    'sphinx_rtd_theme',
]

html_theme = "sphinx_rtd_theme"

中文搜索

安装 jieba

> pip install jieba

编辑 conf.py:

html_search_language = 'zh'
html_show_sourcelink = False