Skip to content

Instantly share code, notes, and snippets.

@nocomplexity
Forked from mgedmin/conf.py.rst
Created April 25, 2017 19:22
Show Gist options
  • Save nocomplexity/8234dcf445c8a770d4ed17ae2ef0ed49 to your computer and use it in GitHub Desktop.
Save nocomplexity/8234dcf445c8a770d4ed17ae2ef0ed49 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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment