更多 Sphinx 自定义

除了使用 Sphinx 核心功能之外,还有两种主要方法可以自定义您的文档:扩展和主题。

启用内置扩展

除了这些配置值外,您还可以通过使用 扩展 来进一步自定义 Sphinx。Sphinx 附带了一些 内置扩展,并且还有更多由 社区维护 的扩展。

例如,要启用 sphinx.ext.duration 扩展,请在您的 conf.py 中找到 extensions 列表,并添加一个元素,如下所示

docs/source/conf.py
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.duration',
]

之后,每次生成文档时,您将在控制台输出的末尾看到一个简短的持续时间报告,如下所示

(.venv) $ make html
...
The HTML pages are in build/html.

====================== slowest reading durations =======================
0.042 temp/source/index

使用第三方 HTML 主题

另一方面,主题是一种自定义文档外观的方法。Sphinx 有几个 内置主题,并且也有 第三方主题

例如,要在您的 HTML 文档中使用 Furo 第三方主题,您需要先使用 Python 虚拟环境中的 pip 安装它,如下所示

(.venv) $ pip install furo

然后,在您的 conf.py 中找到 html_theme 变量,并将其值替换为以下内容

docs/source/conf.py
# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'

有了这个更改,您会注意到您的 HTML 文档现在有了新的外观

HTML documentation of Lumache with the Furo theme

使用 Furo 主题的 Lumache 的 HTML 文档

现在是时候 扩展叙事文档并将其拆分成多个文档 了。