5. HTML Theme¶

本篇章用来讲解 Sphinx 项目的主题设置, Sphinx 项目的默认主题为 "default". 不过由于 default 主题比较难看所以一般都是将主题换为 sphinx_rtd_theme .

备注

可以前往 Sphinx Theme 官网查看 Sphinx 支持的所有的主题.

重要

需要注意的是, Sphinx 项目的主题需要在 conf.py 文件中配置.

5.1. sphinx_rtd_theme 主题配置¶

代码块 5.1.1 sphinx_rtd_theme 主题配置¶

# 头部添加导入
import sphinx_rtd_theme
# 找到主题属性更改如下
html_theme = 'sphinx_rtd_theme'

对于 sphinx_rtd_theme 主题，笔者并没有深入了解其配置，如果读者需要了解可点击链接前往官方文档学习 sphinx_rtd_theme 主题配置。

5.2. sphinx_book_theme 主题配置¶

对于 sphinx_book_theme 主题，如果读者有需要，可点击链接前往官方文档学习 sphinx_book_theme 主题配置。

备注

之所以使用该主题，是为了适应使用 MyST 标记语言的使用，而且 sphinx_rtd_theme 与 sphinx_book_theme 相比，主题不够柔和，而 sphinx_book_theme 还支持 MyST 的一些特殊语法支持如侧边栏的使用。

代码块 5.2.1 sphinx_book_theme 主题配置¶

# 头部添加导入
import sphinx_book_theme
# 找到主题属性更改如下
html_theme = 'sphinx_book_theme'
# 以下为 sphinx_book_theme 的主题配置/定制（sphinx_book_theme）
html_theme_options = {
   # ----------------主题内容中导航栏的功能按钮配置--------
   # 添加存储库链接
   "repository_url": "https://github.com/Eugene-Forest/NoteBook",
   # 添加按钮以链接到存储库
   "use_repository_button": True,
   # 要添加按钮以打开有关当前页面的问题
   "use_issues_button": True,
   # 添加一个按钮来建议编辑
   "use_edit_page_button": True,
   # 默认情况下，编辑按钮将指向master分支，但如果您想更改此设置，请使用以下配置
   "repository_branch": "main",
   # 默认情况下，编辑按钮将指向存储库的根目录；而我们 sphinx项目的 doc文件其实是在 source 文件夹下的，包括 conf.py 和 index(.rst) 主目录
   "path_to_docs": "source",
   # 您可以添加 use_download_button 按钮，允许用户以多种格式下载当前查看的页面
   "use_download_button": True,

   # --------------------------右侧辅助栏配置---------
   # 重命名右侧边栏页内目录名，标题的默认值为Contents。
   "toc_title": "页内目录",
   # 通常，右侧边栏页内目录中仅显示页面的第 2 级标题，只有当它们是活动部分的一部分时（在屏幕上滚动时），才会显示更深的级别。可以使用以下配置显示更深的级别，指示应显示多少级别
   "show_toc_level": 2,

   # --------------------------左侧边栏配置--------------
   # logo 配置
   "logo_only": True,
   # 控制左侧边栏列表的深度展开,默认值为1，它仅显示文档的顶级部分
   "show_navbar_depth": 1,
   # 自定义侧边栏页脚,默认为 Theme by the Executable Book Project
   # "extra_navbar": "<p>Your HTML</p>",
   "home_page_in_toc": True,
   # ------------------------- 单页模式 -----------------
   # 如果您的文档只有一个页面，并且您不需要左侧导航栏，那么您可以 使用以下配置将其配置sphinx-book-theme 为以单页模式运行
   # "single_page": True,
}

代码块 5.2.2 通用配置¶

# 添加你自己的 CSS 规则
html_static_path = ['_static']
html_css_files = ["custom.css"]
# 自定义徽标、和网站图标
html_logo = "./_static/his-own.svg"
html_favicon = "./_static/notebook.svg"