24日

使用sphinx为项目添加多语言文档的一般流程

  1. 在项目根目录下新建docs文件夹，切换至该文件夹。

  2. 创建sphinx空白工程，设置好项目名称，选择语言为英语，选择源码与编译文件分离模式。

sphinx-quickstart

  1. 配置/docs/source/conf.py文件如下

14# -- General configuration ---------------------------------------------------
15# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16
17extensions = [
18    'recommonmark',
19    'sphinx.ext.autodoc',
20    'sphinx.ext.todo',
21    'sphinx.ext.viewcode',
22    'sphinx.ext.githubpages',
23    'sphinx.ext.intersphinx']
24
25templates_path = ['_templates']
26exclude_patterns = []
27
28# -- Options for locale output -------------------------------------------------
29
30# multi-language docs
31language = 'en'
32locale_dirs = ['../locales/']   # path is example but recommended.
33gettext_compact = False  # optional.
34gettext_uuid = True  # optional
35
36
37# -- Options for HTML output -------------------------------------------------
38# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
39
40html_theme = 'furo'
41html_static_path = ['_static']

  1. 配置项目的依赖，位于/docs/requirements.txt路径下。

sphinx
sphinx-markdown-tables==0.0.17
sphinx-autoapi
sphinx-copybutton
sphinx_design
recommonmark
furo

  1. 配置readthedocs网站所需的项目配置文件，位于整个项目的根目录下的'.readthedocs.yaml'，即与/docs目录平级。

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
    os: ubuntu-22.04
tools:
    python: "3.12"
    # You can also specify other tool versions:
    # nodejs: "19"
    # rust: "1.64"
    # golang: "1.19"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
    configuration: docs/source/conf.py

# Optionally build your docs in additional formats such as PDF and ePub
formats:
    - pdf

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
    install:
    - requirements: docs/requirements.txt

  1. 编写英文文档。

  2. 运行下述命令，生成翻译文件。

sphinx-build -b gettext ./source ./build/gettext
sphinx-intl update -p ./build/gettext -l zh_CN

  1. 翻译/docs/locales路径下的待翻译文件。

  2. 上传至github，触发readthedocs的文档项目编译。