Source Buttons#

Source buttons are links to the source of your page’s content (either on your site, or on hosting sites like GitHub).

Add an edit button#

You can add a button to each page that will allow users to edit the page textdirectly and submit a pull request to update the documentation. To include thisbutton in the secondary sidebar of each page, add the following configuration toyourconf.py file in ‘html_theme_options’:

html_theme_options={"use_edit_page_button":True,}

A number of providers are available for buildingEdit this Page links, includingGitHub, GitLab, and Bitbucket. For each, the default public instance URL can bereplaced with a self-hosted instance.

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

Custom Edit URL#

For a fully-customizedEdit this Page URL, provideedit_page_url_template,a jinja2 template string which must contain{{file_name}}, and may referenceany other context values.

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"}

With the predefined providers, the link text reads “Edit on GitHub/GitLab/Bitbucket”.By default, a simple “Edit” is used if you use a custom URL. However, you can seta provider name like this:

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

This will turn the link into “Edit on Provider”.

Custom link text#

You can change the default text by extending theedit-this-page.htmltemplate. For example, if you havetemplates_path=["_templates"]in your Sphinx configuration, you could put this code in_templates/edit-this-page.html:

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

View Source link#

By default, this theme adds a button link to view the source of a page (i.e., the underlyingreStructuredText orMySTMarkdown for the page).To disable it, use the following configuration:

html_show_sourcelink=False