主题结构和布局

本节介绍了一些控制文档布局和结构的基本方法。此主题从 Sphinx Basic NG 主题 继承了其结构和章节术语。

主题布局概述

以下是此主题主要布局的简要概述。请查看图表以了解主要部分的名称。在 html_theme_options 中可以插入组件模板的位置，我们包含变量名称 in inline code。单击章节标题以了解有关它们以及一些基本布局配置的更多信息。有关现有选项的完整参考，请参见 此页面最后一节。

页眉/导航栏

徽标

navbar_start

章节链接

navbar_center

持久组件

navbar_persistent

组件

navbar_end

主侧边栏

活动章节中页面之间的链接。

sidebars

primary_sidebar_end

文章标题

article_header_start article_header_end

文章内容

文章页脚

article_footer_items prev_next_area

辅助侧边栏

页内标题链接

secondary_sidebar_items

页脚内容

content_footer_items

页脚

footer_start footer_center footer_end

水平间距

默认情况下，主题的三个列具有固定宽度。 primary sidebar 将贴靠到左侧， secondary sidebar 将贴靠到右侧， article content 将居中在两者之间。

• 如果缺少一个侧边栏，则 article content 将居中在另一个侧边栏和页面边缘之间。

• 如果两个侧边栏都不存在，则 article content 将位于页面的中间。

如果您希望 article content 占用比默认值更宽的宽度，请使用以下选择器使用 max-width CSS 属性

.bd-main .bd-content .bd-article-container {
  max-width: 100%;  /* default is 60em */
}

上面的规则会将文章内容的最大宽度设置为与顶部导航栏相同的宽度。要真正使用所有可用的页面宽度，您还需要设置以下 CSS 规则

.bd-page-width {
  max-width: 100%;  /* default is 88rem */
}

这将影响文章内容和顶部导航栏。

注意

如果您同时使用以上两个自定义 CSS 规则，请确保将它们作为单独的规则保留在您的 CSS 文件中。如果您将它们合并，结果将是一个比主题中的两个默认规则不太具体的 CSS 选择器，并且您的自定义 CSS 将无法覆盖主题默认值。

模板和组件

有一些主要的主题部分，您可以自定义它们以添加/删除内置组件或添加您自己的组件。每个部分都配置了一系列HTML 模板 - 这些是 Sphinx 插入部分中的 HTML 片段。

您可以选择每个部分中显示哪些模板，以及它们的显示顺序。此页面描述了您可以自定义的主要区域。

注意

在每个部分中配置模板时，如果您愿意，可以省略每个模板后的 .html 后缀。

页眉/导航栏

位于 sections/header.html 中。

页眉位于所有其他内容之上的页面顶部，包含网站级信息。

页眉部分

页眉被分成三个部分。每个部分在 conf.py 中使用以下配置进行配置

• 左侧部分： html_theme_options['navbar_start']

• 中间菜单： html_theme_options['navbar_center']

• 右侧部分： html_theme_options['navbar_end']

• 持久右侧部分： html_theme_options['navbar_persistent']

默认情况下，将使用以下配置

html_theme_options = {
# ...
"navbar_start": ["navbar-logo"],
"navbar_center": ["navbar-nav"],
"navbar_end": ["navbar-icon-links"],
"navbar_persistent": ["search-button"]
# ...
}

警告

持久右侧部分放置在 navbar_end 旁边，但其元素即使在小屏幕上（当所有其他元素折叠时）也会保留在页眉中可见。它专门设计用于 search-button，我们无法保证它与其他组件的兼容性。

配置导航栏中心对齐方式

默认情况下，导航栏中心区域将与页面上的内容对齐。这等于以下默认配置

html_theme_options = {
   # ...
   "navbar_align": "content"
   # ...
}

相反，如果您希望这些项目贴靠到左侧（更靠近徽标），请使用以下配置

html_theme_options = {
   # ...
   "navbar_align": "left"
   # ...
}

如果您希望这些项目贴靠到页面的右侧，请使用以下配置

html_theme_options = {
   # ...
   "navbar_align": "right"
   # ...
}

文章标题

位于 sections/header-article.html 中。

文章标题是文章内容正上方的一条窄条。有两个子部分可以添加组件模板

• article_header_start 对齐到文章标题的开头（左侧）。默认情况下，此部分包含 breadcrumbs.html 组件，该组件显示到当前页面父页面的链接。

• article_header_end 对齐到文章标题的结尾（右侧）。默认情况下，此部分为空。

主侧边栏（左侧）

位于 sections/sidebar-primary.html 中。

主侧边栏位于页面主要内容的左侧。它主要用于章节间导航。默认情况下，它将显示当前活动顶级章节的任何同级/子级链接（对应于您页眉导航栏中的链接）。

配置它与配置其他部分略有不同，因为配置侧边栏是 Sphinx 本身支持的，通过 html_sidebars 配置变量。

仅对于主侧边栏，您可以配置模板，使它们仅在某些页面上显示。您可以在 conf.py 中使用以下配置来实现这一点

html_sidebars = {
    "<page_pattern>": ["list", "of", "templates"]
}

与 <page_pattern> 匹配的任何页面都将插入其相应的模板。您还可以使用 * 来进行 glob 样式匹配，并且可以使用 ** 来匹配所有页面。

默认情况下，它具有以下配置

html_sidebars = {
    "**": ["sidebar-nav-bs", "sidebar-ethical-ads"]
}

• sidebar-nav-bs.html - 一个 Bootstrap 友好的导航部分。

  当没有页面要显示时，它将消失，并且可能会为页面的内容添加额外的空间。

• sidebar-ethical-ads.html - ReadTheDocs 的道德广告的放置位置（仅在 ReadTheDocs 上显示）。

主侧边栏结束部分

主侧边栏内有一个特殊的 <div>，它会出现在页面底部，与上面的内容无关。

要控制此 div 中的 HTML 模板，请在 conf.py 中使用 html_theme_options['primary_sidebar_end']。

默认情况下，它具有以下模板

html_theme_options = {
  # ...
  "primary_sidebar_end": ["sidebar-ethical-ads"],
  # ...
}

从页面中删除主侧边栏

如果您希望从页面中删除主侧边栏，您可以在 conf.py 中使用以下配置

html_sidebars = {
  "pagename": []
}

这适用于 glob 样式模式。例如

html_sidebars = {
  "folder/*": []
}

如果你想从所有文档页面中删除主侧边栏，请使用此模式

html_sidebars = {
  "**": []
}

页脚内容

位于 sections/footer-content.html 中。

页脚内容是一个窄条，跨越文章内容和次级侧边栏。它不包含任何读者可以直接看到的内容，但作为占位符保留，以备主题开发者将来需要重新使用它。

次级侧边栏（右侧）

位于 sections/sidebar-secondary.html 中。

页面内侧边栏位于页面文章内容的右侧，并在 conf.py 中使用 html_theme_options['secondary_sidebar_items'] 进行配置。

默认情况下，它具有以下模板

html_theme_options = {
  # ...
  "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
  # ...
}

要了解如何进一步自定义或删除次级侧边栏，请查看 页面目录。

文章页脚

位于 sections/footer-article.html 中。

文章页脚位于页面文章下方。默认情况下，它不包含任何读者可以直接看到的内容，但作为自定义或内置模板的占位符保留。

html_theme_options = {
  # ...
  "article_footer_items": [],
  # ...
}

隐藏上一个和下一个按钮

默认情况下，您网站的每个页面底部都会在 prev_next_area 中显示“上一个”和“下一个”按钮。您可以使用以下配置隐藏这些按钮

html_theme_options = {
  "show_prev_next": False
}

内容页脚

位于 sections/footer-content.html 中。

内容页脚位于页面文章和次级侧边栏下方。默认情况下它是空的，但您可以使用以下配置添加模板到它

html_theme_options = {
  # ...
  "content_footer_items": ["your-template.html"],
  # ...
}

页脚

位于 sections/footer.html 中。

页脚位于页面主要内容下方，并在 conf.py 中使用 html_theme_options['footer_start']、html_theme_options['footer_center'] 和 html_theme_options['footer_end'] 进行配置。

默认情况下，footer_center 为空，footer_start 和 footer_end 具有以下模板

html_theme_options = {
  #...
  "footer_start": ["copyright", "sphinx-version"],
  "footer_end": ["theme-version"]
  #...
}

在每个子部分中，组件将垂直堆叠。如果你想让它们水平堆叠，请使用以下自定义 CSS 规则

.footer-items__start, .footer-items__end {
  flex-direction: row;
}

内置组件插入到部分中

下面列出了可以插入到任何部分的内置模板。请注意，其中一些可能具有假设特定部分的 CSS 规则（并将相应命名）。

注意

在添加/更改/覆盖组件时，“.html”后缀是可选的。这就是为什么在下面的列表中它们都显示为没有它。

• breadcrumbs: 显示（并链接到）当前查看页面的父部分。

• copyright: 显示版权信息（在 conf.py 中定义）。

• edit-this-page: 显示一个链接到指定版本控制系统中页面源的编辑界面。

• icon-links: 将图标链接显示为列表项。

• indices: 显示指向 Sphinx 生成的索引（genindex、modindex、py-modindex）的链接。

• last-updated: 显示文档最后构建的日期和时间。

• navbar-icon-links: 在页眉导航栏中显示图标链接。

• navbar-logo: 在页眉导航栏中显示您的文档网站的徽标。

• navbar-nav: 在页眉导航栏中显示指向顶级 TOCtree 元素的链接。

• page-toc: 显示当前页面的目录。

• prev-next: 显示指向 TOCtree 顺序中上一个和下一个页面的链接。

• search-button-field: 显示一个搜索字段图像，单击该图像会打开一个搜索叠加层。

• search-button: 显示一个放大镜图标，单击该图标会打开一个搜索叠加层。

• search-field: 在页面上直接显示一个交互式搜索字段。

• searchbox: 一个空容器，当需要时，它包含“隐藏搜索匹配项”按钮。

• sidebar-ethical-ads: 对于托管在 ReadTheDocs 上的网站，显示“道德广告”。

• sidebar-nav-bs: 显示当前活动顶级 TOCtree 元素下嵌套的页面的 TOC 子树。

• sourcelink: 显示指向当前页面的 .rst 源代码的链接。

• sphinx-version: 显示用于构建文档的 Sphinx 版本。

• theme-switcher: 显示一个图标，用于在浅色模式、深色模式和自动（使用浏览器的设置）之间切换。

• theme-version: 显示用于构建文档的 pydata-sphinx-theme 版本。

• version-switcher: 显示一个下拉框，用于在文档的不同版本之间切换。

将您自己的 HTML 模板添加到主题部分

如果你想将你自己的自定义模板添加到这些部分中的任何一个，你可以按照以下步骤进行

1. 在名为 _templates 的文件夹中创建一个 HTML 文件。例如，如果你想使用 Jinja 模板显示文档的版本，你可以创建一个文件：_templates/version.html 并将以下内容放入其中

   <!-- This will display the version of the docs -->
   {{ version }}
   

2. 现在将文件添加到上面部分之一的菜单项中。例如

   html_theme_options = {
   # ...
   "navbar_start": ["navbar-logo", "version"],
   # ...
   }
   

构建日期

默认情况下，即使 Sphinx 的 html_last_updated_fmt 变量已设置，此主题也不会显示构建日期。如果你想显示构建日期，主题包含一个 last-updated 模板，你可以将其添加到 conf.py 中的页面区域之一。例如

conf.py

html_theme_options = {
    "content_footer_items": ["last-updated"],
    # other settings...
}

如果你确实指定了 html_last_updated_fmt，但没有包含 last-updated 模板，主题仍然会将构建日期写入 HTML 页眉中的 meta 标记，可以通过查看页面源代码或使用 HTML 解析器提取该标记。该标记将如下所示

<meta name="docbuild:last-update" content="Aug 15, 2023">

该标记的 content 属性将遵循 html_last_updated_fmt 配置变量中指定的格式。

参考资料

请在此找到可以在 conf.py 中的 html_theme_options 中使用的所有键的完整列表

[theme]
inherit = basic
# Note that we don't link the CSS file via Sphinx
# instead we manually link it in `webpack-macros.html`
stylesheet = styles/pydata-sphinx-theme.css
pygments_style = tango
sidebars = sidebar-nav-bs.html

[options]
# General configuration
sidebarwidth = 270
sidebar_includehidden = True
use_edit_page_button = False
external_links =
bitbucket_url =
github_url =
gitlab_url =
twitter_url =
icon_links_label = Icon Links
icon_links =
analytics =
show_prev_next = True
search_bar_text = Search the docs ...
navigation_with_keys = False
collapse_navigation = False
navigation_depth = 4
show_nav_level = 1
show_toc_level = 1
navbar_align = content
header_links_before_dropdown = 5
header_dropdown_text = More
switcher =
check_switcher = True
pygments_light_style = a11y-high-contrast-light
pygments_dark_style = a11y-high-contrast-dark
logo =
logo_link =
surface_warnings = True
back_to_top_button = True

# Template placement in theme layouts
navbar_start = navbar-logo
navbar_center = navbar-nav
navbar_end = theme-switcher, navbar-icon-links
navbar_persistent = search-button-field
article_header_start = breadcrumbs
article_header_end =
article_footer_items =
content_footer_items =
primary_sidebar_end = sidebar-ethical-ads
footer_start = copyright, sphinx-version
footer_center =
footer_end = theme-version
secondary_sidebar_items = page-toc, edit-this-page, sourcelink
show_version_warning_banner = False
announcement =

# DEPRECATED (remove after 1.0 release)
pygment_light_style =
pygment_dark_style =