链接到源文件的按钮

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

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,
    ...
}