← back

Sphinx使用

通过sphinx完成对文档的管理，并借助rtd进行托管

Why Sphinx

有许多开源工具可以用来将纯文本转换为静态网页，选择 Sphinx 的理由有以下几点：

Getting Started

Installation and Quick Start

pip3 install sphinx

sphinx-quickstart # 根据提示自由开始设置
# Separate source and build directories (y/n) [n]: n # 不分离，待会儿ignore即可
# Project name: xxx # 工程名，可稍后在 conf.py文件中修改
# Author name(s): xxx # 作者名，可稍后在 conf.py文件中修改
# Project release []: # release version , 可稍后在 conf.py文件中修改
# Project language [en]: en # 默认为英文，简体中文为zh_CN , 可稍后在 conf.py文件中修改

make html # 编译，编译通过后，使用浏览器查看_build/html/index.html即可查看到网页

Personalized configuration

setting theme

修改conf.py中对应的theme部分

# html_theme = 'alabaster'
# html_static_path = ['_static']

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

adding extension

extensions = [
    "recommonmark", # 启用markdown支持
    "sphinx_markdown_tables", # 启用markdown表格支持
    "sphinx.ext.autosectionlabel",
    "sphinx_copybutton", # 启用复制
]

Add Article

每个sphinx工程的根目录中的index.rst是文档的首页，添加新的文章只需要按照如下语法添加即可

.. toctree::
   :maxdepth: 1
   :caption: Get Started

   getting_started.md

Deployed Instance

接下来通过一个具体的实例展示如何将sphinx的双语文档上传至github，再借助read the docs对文档进行托管，以及语言切换。工程参考自我的一个小工具项目wadda

project structure

如下结构是一个比较优雅的文档结构

wadda
├── docs
│   ├── en # 英文文档路径
│   ├── requirements.txt # 记录环境的依赖，最好具体到小的版本
│   └── zh_cn # 中文文档路径
│ .readthedocs.yml # read the doc的入口文件
│ ...

.readthedocs.yml & requirements.txt

.readthedocs.yml

该文件存在于工程根路径时，readthedoc导入时将根据其内容设置read the doc部署环境

version: 2
formats: all
build:
  os: ubuntu-20.04
  tools:
    python: "3.8"
python:
  install:
    - requirements: docs/requirements.txt # 指定requirements的路径

requirements.txt

设置本地sphinx的具体环境配置，read the doc需要依赖此信息分配一个虚拟机进行文档的拉取和编译

sphinx==5.1.1
sphinx_rtd_theme==1.0.0 # read the doc 的文档主题
recommonmark==0.7.1 # 使shpinx可以支持markdown的插件
sphinx-markdown-tables # 使得上述的markdown插件支持table的插件
sphinx-copybutton # 在文档中有复制按钮

conf.py

sphinx工程内的配置文件，sphinx的设置都在这个文件中配置

project = "project_name"
copyright = "2022, windzu"
author = "windzu"
release = "latest"

# 设置使用的插件
extensions = [
    "recommonmark", # 启用markdown支持
    "sphinx_markdown_tables", # 启用markdown表格支持
    "sphinx.ext.autosectionlabel",
    "sphinx_copybutton", # 启用复制
]

templates_path = ["_templates"]

# The suffix(es) of source filenames.
# 如果启用了markdown支持，这里要设置一下在文档生产时候扫描的后缀
source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}

exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

# 设置语言
language = "zh_CN" # 默认无，指带en 简体中文为 zh_CN

# 设置主题
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme" # 个人最喜欢的read the doc的主题
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# 设置静态文档路径
html_static_path = ["_static"]

read the doc中设置

准备工作

  1. 将上述工程上传至github
  2. 使用github帐号注册readthedocs

导入英文版文档

英文版需为主文档，这样后续才可以和其他语言的绑定。如果是手动导入，记得选择高级设置，选择正确的仓库分支，readthedoc默认选择master分支，但是目前github默认的主分支为main，这会导致构建错误

  1. 从readthedoc设置中，从列出的github仓库列表中选择刚才的工程，如果没有出现就选择手动导入，填写仓库地址，设置注意点：语言设置为**英文,**其他自由设置即可
  2. 创建完毕后，在该项目的管理 - 高级设置 - Python配置文件 处填写英文版文档的conf文件，在本示例中为 docs/en/conf.py

导入中文版文档

与英文几乎一致，但是请注意，其工程必须是手动导入，否则会冲突

  1. 从readthedoc设置中，从列出的github仓库列表中选择刚才的工程，如果没有出现就选择手动导入，填写仓库地址，设置注意点：语言设置为简体中文,其他自由设置即可，工程名在英文版的基础上添加_zh_CN后缀
  2. 创建完毕后，在该项目的管理 - 高级设置 - Python配置文件 处填写英文版文档的conf文件，在本示例中为 docs/zh_cn/conf.py

英文版绑定中文版

设置完成后，可以在英文文档界面中切换语言

在英文文档的项目中，选择 管理 - 翻译

然后在其中选择刚才所构建的中文版本文档，添加即可，过一会儿就可在英文文档主页中进行不同语言版本的文档切换，如wadda文档所示