如何让Sphinx识别并使用自定义主题？

1. 配置主题搜索路径 #

在docs/conf.py中添加自定义主题的路径配置，让Sphinx能定位到同级的custom_theme目录：

import os
html_theme_path = [os.path.abspath('../')]

2. 修正主题目录结构 #

Sphinx要求主题的模板文件必须放在_templates子目录下，调整你的文件夹结构为：

.
docs
   conf.py
   makefile
   make.bat
   index.md
custom_theme
   theme.toml
   _templates
      layout.html

3. 确保theme.toml内容合规 #

检查custom_theme/theme.toml的必填字段是否完整，主题名称必须和conf.py中html_theme的值一致：

[theme]
name = "custom_theme"
version = "0.1.0"
description = "自定义Sphinx主题"

4. 重新构建文档 #

再次执行你的构建命令即可：

sphinx-autobuild -a docs docs/_build/html --watch custom_theme

内容的提问来源于stack exchange，提问作者Skrillx