21日

今天是校庆日，也是一个新的起点！那就开始奋斗吧！

sphinx介绍

这是一个用sphinx编写的文档。而关于其介绍可参见以下网址：

  1. 权威指南

  2. 快速入门

sphinx的安装

基于python环境，需要安装的package包括

$ pip install sphinx sphinx-intl

sphinx的主题

参见 主题网站,最爱 furo。

一些配置文件

requirements.txt

一般位于/docs/requirements.txt路径下。其中记录了当前sphinx工程的依赖关系。

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

conf.py

一般位于/docs/source/conf.py路径下，其中记录了当前sphinx工程的主要配置。 除项目名等信息外，其他的配置内容类似下列内容

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'recommonmark',
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.intersphinx']

templates_path = ['_templates']
exclude_patterns = []

# -- Options for locale output -------------------------------------------------

# multi-language docs
language = 'en'
locale_dirs = ['../locales/']   # path is example but recommended.
gettext_compact = False  # optional.
gettext_uuid = True  # optional


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'furo'
html_static_path = ['_static']

多语言的sphinx项目

sphinx对多语言间的翻译和转换支持比较好，配合一些工具可以将这一功能发挥得更好。 具体步骤如下：

  1. 用英文进行原始项目编写。

  2. 按上述实例设置conf.py文件。

  3. 生成初始翻译文件。

$ sphinx-build -b gettext . ../build/gettext

若以/docs/source为当前目录，上述命令运行后会生成/docs/build/gettext路径下生成与源文件对应的.pot文件，，这些文件包含了所有需要翻译的文本，如下所示。

19#: ../../index.rst:9
20msgid "Contents:"
21msgstr ""

  1. 初始化翻译，生成中间文件。使用 sphinx-intl 命令初始化翻译。这个命令会根据 .pot 文件生成对应语言的 .po 文件。

$ sphinx-intl update -p ../build/gettext -l zh_CN

此步骤会在 locale 目录中生成zh_CN语言的翻译文件的空白.po文件，效果如下。

22#: ../../index.rst:9
23msgid "Contents:"
24msgstr ""

  1. 对上述中间文件进行编辑，添加对应的翻译。翻译完的效果如下所示：

22#: ../../index.rst:9
23msgid "Contents:"
24msgstr "目录"

  1. 构建多语言文档

html:
    sphinx-build -b html -D language=en . ../build/html/en
    sphinx-build -b html -D language=zh_CN . ../build/html/zh_CN

  1. 验证和上传。生成多语言文档并上传到 GitHub。然后在 Read the Docs 中配置多语言支持，确保不同语言的文档能够自动构建和更新。