跳转至主要内容
Ctrl+K
⚠️The latest release refactored our HTML, so double-check your custom CSS rules!⚠️
Sphinx Book Theme - Home Sphinx Book Theme - Home
  • Executable Books
  • GitHub
  • PyPI

主题领域

  • 快速上手
  • 内容与格式
    • 特殊内容块
    • PyData 主题元素
    • Jupyter notebooks
    • 用于交互的启动按钮
  • 布局和主要分区
    • 主侧边栏和导航
    • 辅助侧边栏和目录
    • 页眉和导航栏
    • 内容页脚
    • 页面页脚
    • 公告横幅
  • 组件定制
    • logo与品牌
    • 图标链接和徽章
    • 添加下载页面按钮
    • 链接到源文件的按钮
    • 添加您自己的 CSS 规则
  • Reference of theme options
  • 贡献指南
    • Set up your development workflow
    • 项目结构
    • Style and design
    • Testing infrastructure
    • Releases and version numbers
    • Translation workflow
    • Creating sub-themes
  • Changelog

示例页面

  • Kitchen Sink
    • Admonitions
    • API documentation
    • Blocks
    • Generic items
    • Images & Figures
    • Lists
    • Really Long Page Title because we should test sidebar wrapping
    • Structural Elements
    • Tables
    • Typography
  • Theme-specific elements
  • Sphinx extension styles
  • Jupyter notebooks
  • Thebe
  • Reference for Blog
  • NumPy docstrings
  • Comments
  • Show source
  • Suggest edit
  • Open issue
  • .md

链接到源文件的按钮

Contents

  • Set your source repository
    • 手动指定提供商
  • 添加页面源代码按钮
  • 添加建议编辑按钮
  • 添加到您的仓库的链接
  • 添加打开问题按钮

链接到源文件的按钮#

您可以使用一组按钮链接到您的源代码仓库。这使用户可以浏览仓库,或执行诸如建议编辑或提交问题等操作。

Set your source repository#

要使此功能正常工作,您需要定义 源代码仓库。这是托管您的代码/文档的在线空间。在每种情况下,它们都需要以下配置存在:

html_theme_options = {
    ...
    "repository_url": "https://{your-provider}/{org}/{repo}",
    ...
}

支持三种提供商:

  • GitHub:例如,https://github.com/executablebooks/sphinx-book-theme。这包括自托管 GitHub 的自定义 URL。

  • GitLab:例如,https://gitlab.com/gitlab-org/gitlab。这包括自托管 GitLab 的自定义 URL。

  • BitBucket: 例如,https://opensource.ncsa.illinois.edu/bitbucket/scm/u3d/3dutilities。

在每种情况下,我们假设最后两个 URL 项是 org/repo 对

手动指定提供商#

如果您的提供商 URL 更复杂(例如,如果您正在自托管您的提供商),您可以使用以下配置手动指定提供商:

html_theme_options = {
    ...
    "repository_provider": "gitlab"  # or "github", "bitbucket",
    "repository_url": "selfhostedgh.mycompany.org/user/repo",
    ...
}

提供了这些信息后,您可以按照以下各节添加源代码按钮。

添加页面源代码按钮#

在您提供的提供商上显示页面的原始源代码。要添加页面源代码按钮,首先配置您的源代码仓库,然后添加:

html_theme_options = {
    ...
    "use_source_button": True,
    ...
}

然后配置要用于源代码的 存储库分支。默认情况下,它是 main,但如果您想更改此设置,请使用以下配置:

html_theme_options = {
    ...
    "repository_branch": "{your-branch}",
    ...
}

最后,配置到您文档的相对路径。默认情况下,这是存储库的根目录,但如果您的文档托管在子文件夹中,请使用以下配置:

html_theme_options = {
    ...
    "path_to_docs": "{path-relative-to-site-root}",
    ...
}

添加建议编辑按钮#

允许用户直接在提供商上编辑页面文本并提交拉取请求以更新文档。要添加编辑页面按钮,首先配置您的源代码仓库,然后添加:

html_theme_options = {
    ...
    "use_edit_page_button": True,
    ...
}

然后按照源文件部分中的分支和相对路径说明。

添加到您的仓库的链接#

添加到您的仓库的链接,请添加以下配置:

html_theme_options = {
    ...
    "use_repository_button": True,
    ...
}

添加打开问题按钮#

要添加关于当前页面的问题按钮,请使用以下配置:

html_theme_options = {
    ...
    "use_issues_button": True,
    ...
}

上一页

添加下载页面按钮

下一页

添加您自己的 CSS 规则

Contents
  • Set your source repository
    • 手动指定提供商
  • 添加页面源代码按钮
  • 添加建议编辑按钮
  • 添加到您的仓库的链接
  • 添加打开问题按钮

By the Executable Book Project

© Copyright 2023.

最后更新于 2024 年 12 月 23 日.