源按钮#

源按钮是链接到页面内容源的链接（无论是在您的网站上，还是在 GitHub 等托管网站上）。

添加编辑按钮#

您可以为每个页面添加一个按钮，允许用户直接编辑页面文本并提交拉取请求以更新文档。要将此按钮包含在每个页面的辅助侧边栏中，请将以下配置添加到您在 `html_theme_options` 中的 `conf.py` 文件中

html_theme_options = {
    "use_edit_page_button": True,
}

有多个提供商可用于构建“编辑此页面”链接，包括 GitHub、GitLab 和 Bitbucket。对于每个提供商，都可以用自托管实例替换默认的公共实例 URL。

GitHub#

html_context = {
    # "github_url": "https://github.com", # or your GitHub Enterprise site
    "github_user": "<your-github-org>",
    "github_repo": "<your-github-repo>",
    "github_version": "<your-branch>",
    "doc_path": "<path-from-root-to-your-docs>",
}

GitLab#

html_context = {
    # "gitlab_url": "https://gitlab.com", # or your self-hosted GitLab
    "gitlab_user": "<your-gitlab-org>",
    "gitlab_repo": "<your-gitlab-repo>",
    "gitlab_version": "<your-branch>",
    "doc_path": "<path-from-root-to-your-docs>",
}

Bitbucket#

html_context = {
    # "bitbucket_url": "https://bitbucket.org", # or your self-hosted Bitbucket
    "bitbucket_user": "<your-bitbucket-org>",
    "bitbucket_repo": "<your-bitbucket-repo>",
    "bitbucket_version": "<your-branch>",
    "doc_path": "<path-from-root-to-your-docs>",
}

自定义编辑 URL#

对于完全自定义的“编辑此页面”URL，请提供 `edit_page_url_template`，这是一个 jinja2 模板字符串，它必须包含 `{{ file_name }}`，并且可以引用任何其他上下文值。

html_context = {
    "edit_page_url_template": "{{ my_vcs_site }}{{ file_name }}{{ some_other_arg }}",
    "my_vcs_site": "https://example.com",
    "some_other_arg": "?some-other-arg"
}

对于预定义的提供商，链接文本显示为“在 GitHub/GitLab/Bitbucket 上编辑”。默认情况下，如果您使用自定义 URL，则使用简单的“编辑”。但是，您可以这样设置提供商名称

html_context = {
    "edit_page_url_template": "...",
    "edit_page_provider_name": "Provider",
}

这会将链接更改为“在提供商上编辑”。

自定义链接文本#

您可以通过扩展 `edit-this-page.html` 模板来更改默认文本。例如，如果您的 Sphinx 配置中包含 `templates_path = ["_templates"]`，则可以将以下代码放入 `_templates/edit-this-page.html` 中

{% extends "!components/edit-this-page.html" %}

{% block edit_this_page_text %}
  Edit this page
{% endblock %}