github github-pages python-sphinx read-the-docs

How do I replace "View page source" with "Edit on GitHub" links in sphinx_rtd_theme?

How can I replace the View page source hyperlink at the top of my docs pages with a Edit on GitHub link when building a Sphinx site using the sphinx_rtd_theme theme?

I'm manually building a readthedocs.io-like site using GitHub Pages, but the link in the top-right of all my doc's pages still says "View page source" instead of "Edit on GitHub."

The theme's documentation lists a few relevant options (display_github, vcs_pageview_mode, and github_url), but it provides no examples. I've tried setting them at the root of conf.py and in html_theme_options to no avail.

How can I tell the sphinx_rtd_theme theme to change the View page source link to an Edit on GitHub link on all my docs' pages?

Solution

You should set the display_github, github_user, github_repo, and github_version variables inside the html_context dict in conf.py. For example:

html_context = {
  'display_github': True,
  'github_user': 'buskill',
  'github_repo': 'buskill-app',
  'github_version': 'master/docs/',
}

These variables are intended to be set directly in the .rst files rather than in html_theme_options or conf.py in general. To make this actually apply site-wide as if it were defined in every .rst file, just put it in html_context.