更多 Sphinx 自定义¶
除了使用 Sphinx 核心功能之外,还有两种主要方法可以自定义您的文档:扩展和主题。
启用内置扩展¶
除了这些配置值外,您还可以通过使用 扩展 来进一步自定义 Sphinx。Sphinx 附带了一些 内置扩展,并且还有更多由 社区维护 的扩展。
例如,要启用 sphinx.ext.duration
扩展,请在您的 conf.py
中找到 extensions
列表,并添加一个元素,如下所示
# 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
变量,并将其值替换为以下内容
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
有了这个更改,您会注意到您的 HTML 文档现在有了新的外观
现在是时候 扩展叙事文档并将其拆分成多个文档 了。