更多 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 第三方主题，首先您需要使用 pip 在您的 Python 虚拟环境中安装它，就像这样

(.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 文档¶

现在是时候扩展叙述性文档并将其拆分为多个文档了。