跳至主要内容
Ctrl+K

PyData 主题

  • 用户指南
  • 贡献者指南
  • 示例
  • 变更日志
    • API
    • PyData 网站
    • NumFocus
    • 捐赠给 NumFocus
  • Twitter
  • GitHub
  • PyPI
  • PyData
  • 用户指南
  • 贡献者指南
  • 示例
  • 变更日志
  • API
  • PyData 网站
  • NumFocus
  • 捐赠给 NumFocus
  • Twitter
  • GitHub
  • PyPI
  • PyData

章节导航

入门

  • 安装
  • 主题结构和布局

导航和链接

  • 导航深度和折叠侧边栏
  • 页面目录
  • 页眉链接
  • 源按钮
  • Sphinx 索引

用户界面

  • 公告横幅
  • 版本切换下拉菜单
  • 搜索栏 / 搜索按钮
  • 键盘快捷键
  • 国际化
  • 返回顶部按钮

内容和功能

  • 主题特定元素
  • 使用 ABlog 的博客
  • Sphinx 设计组件
  • 扩展主题

主题和样式

  • 品牌和徽标
  • 主题变量和 CSS
  • 字体和 FontAwesome
  • 浅色和深色主题

其他

  • 无障碍性
  • 分析和使用服务
  • 添加自定义 CSS 和 JS 资产
  • 构建性能和大小
  • 主题更改、弃用和警告
  • Read the Docs 功能
  • 用户指南
  • 品牌和徽标

品牌和徽标#

自定义徽标和标题#

默认情况下,该主题将在页眉导航栏的左侧使用 project 的值。这可以使用徽标图像替换,并且可以选择使用自定义的 html_title。

适用于浅色和深色模式的单个徽标#

要使用本地图像文件,请使用如Sphinx 文档中指定的 html_logo。该文件必须相对于 conf.py。例如,如果您的文档在 _static/logo.png 中有一个徽标

html_logo = "_static/logo.png"

要使用指向图像的外部链接,请确保 html_logo 以 http 开头。例如

html_logo = "https://pydata.org/wp-content/uploads/2019/06/pydata-logo-final.png"

适用于浅色和深色模式的不同徽标#

您可以为“浅色”和“深色”模式指定不同版本的徽标图像。如果您的徽标图像不适合深色模式(浅色背景,对比度不足等),这将很有用。

为此,请在 html_theme_options 中使用 logo["image_light"] 和 logo["image_dark"] 选项。对于每个选项,请提供相对于 conf.py 的路径,如下所示

# Assuming your `conf.py` has a sibling folder called `_static` with these files
html_theme_options = {
   "logo": {
      "image_light": "_static/logo-light.png",
      "image_dark": "_static/logo-dark.png",
   }
}

注意

image_light 和 image_dark 将覆盖 html_logo 设置。如果您只指定了浅色或深色变体之一,则未指定的变体将回退到 html_logo 的值。

自定义徽标链接#

徽标默认链接到 root_doc(通常是您文档的第一页)。您可以改为链接到本地文档或外部链接网站。为此,请使用 html_theme_options["logo"]["link"] 选项并提供新的链接。

例如,要引用另一个本地页面

html_theme_options = {
    "logo": {
        "link": "some/other-page",
    }
}

要引用外部网站,请确保您的链接以 http 开头

html_theme_options = {
    "logo": {
        "link": "https://pydata.org",
    }
}

徽标标题和替代文本#

如果您提供徽标图像,它将在页眉导航栏中替换 project 或 html_title。如果您希望在徽标旁边同时显示网站的徽标和标题(或任何其他文本),请使用 text 属性,如下所示

conf.py#
html_theme_options = {
    "logo": {
        "text": "My awesome documentation",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

但是,如果您只想显示徽标而不显示网站标题,那么最好提供替代文本,这将有助于盲人访问者和其他依赖屏幕阅读器的用户

conf.py#
html_theme_options = {
    "logo": {
        # Because the logo is also a homepage link, including "home" in the
        # alt text is good practice
        "alt_text": "My awesome documentation - Home",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

在大多数情况下,您将提供 text 或 alt_text,而不是两者,但有些情况下可能需要同时提供两者

conf.py#
html_theme_options = {
    "logo": {
        # In a left-to-right context, screen readers will read the alt text
        # first, then the text, so this example will be read as "P-G-G-P-Y
        # (short pause) Home A pretty good geometry package"
        "alt_text": "PggPy - Home",
        "text": "A pretty good geometry package",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

如果您没有提供 text 或 alt_text,该主题将提供一些默认的替代文本(否则,您的主页链接将显示为辅助技术,例如“未标记的图像”)。默认替代文本为“docstitle - Home”,但是如果您提供徽标标题 (text),则默认替代文本将为空字符串(假设如果您提供徽标标题,则标题可能正在执行替代文本的工作,如上所示,您可以通过同时提供 text 和 alt_text 来覆盖此假设)。

添加图标#

pydata_sphinx_theme 支持使用 html_favicon 的标准 sphinx 图标配置。对复杂和多个图标的支持在 0.15.3 版中被删除。相反,请使用 sphinx-favicon 扩展。它使用更灵活的参数提供相同的功能。

previous

扩展主题

next

主题变量和 CSS

本页内容
  • 自定义徽标和标题
    • 适用于浅色和深色模式的单个徽标
    • 适用于浅色和深色模式的不同徽标
    • 自定义徽标链接
    • 徽标标题和替代文本
  • 添加图标
在 GitHub 上编辑
显示源代码

© 版权所有 2019,PyData 社区。

使用 Sphinx 8.1.3 创建。

使用 PyData Sphinx 主题 0.16.0 构建。