更多 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 文档现在有了一个新的外观:

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