Skip to content

Instantly share code, notes, and snippets.

@mgedmin
Created July 22, 2013 10:37
Show Gist options
  • Save mgedmin/6052926 to your computer and use it in GitHub Desktop.
Save mgedmin/6052926 to your computer and use it in GitHub Desktop.
HOWTO add "Show on GitHub" and "Edit on GitHub" links to the Sphinx sidebar

Edit on GitHub links for Sphinx

Create _ext/ and _templates/ subdirectories.

Move edit_on_github.py into the _ext/ subdirectory.

Move sourcelink.html into the _templates/ subdirectory.

Add the following after the import sys, os line :

sys.path.insert(0, os.path.abspath('_ext'))

Add edit_on_github to the list of extensions :

extensions = ['edit_on_github']

Configure the extension :

edit_on_github_project = 'username/reponame'
edit_on_github_branch = 'master'

Make sure the template path is specified correctly :

templates_path = ['_templates']
"""
Sphinx extension to add ReadTheDocs-style "Edit on GitHub" links to the
sidebar.
Loosely based on https://github.com/astropy/astropy/pull/347
"""
import os
import warnings
__licence__ = 'BSD (3 clause)'
def get_github_url(app, view, path):
return 'https://github.com/{project}/{view}/{branch}/{path}'.format(
project=app.config.edit_on_github_project,
view=view,
branch=app.config.edit_on_github_branch,
path=path)
def html_page_context(app, pagename, templatename, context, doctree):
if templatename != 'page.html':
return
if not app.config.edit_on_github_project:
warnings.warn("edit_on_github_project not specified")
return
path = os.path.relpath(doctree.get('source'), app.builder.srcdir)
show_url = get_github_url(app, 'blob', path)
edit_url = get_github_url(app, 'edit', path)
context['show_on_github_url'] = show_url
context['edit_on_github_url'] = edit_url
def setup(app):
app.add_config_value('edit_on_github_project', '', True)
app.add_config_value('edit_on_github_branch', 'master', True)
app.connect('html-page-context', html_page_context)
@tk0miya
Copy link

tk0miya commented May 28, 2016

It seems this extension has conflicted with sphinx.ext.viewcode.
_module/index.html is generated as a index of modules if you use sphinx.ext.viewcode. But it causes the error in edit_on_github because the page does not have doctree.
ref: sphinx-doc/sphinx#2506

@sgala
Copy link

sgala commented Jul 24, 2016

add something like

if not doctree: return

before the definition of path. There will be no "edit" or "source" link in pages that have no doctree

@viveleroi
Copy link

I'm using this for a custom need but I'm using a custom theme, how can I get the links to show up?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment