Instantly share code, notes, and snippets.

Embed
What would you like to do?
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)
@westurner

This comment has been minimized.

Show comment
Hide comment
@westurner

westurner commented Jan 1, 2015

Packaged and extended as https://pypi.python.org/pypi/sphinxcontrib-srclinks ... Thanks!

@jcbrand

This comment has been minimized.

Show comment
Hide comment
@jcbrand

jcbrand May 1, 2015

@westurner The instruction says I must run git clone https://bitbucket.org/westurner/sphinxcontrib-srclinks but that repo is not publically available.

jcbrand commented May 1, 2015

@westurner The instruction says I must run git clone https://bitbucket.org/westurner/sphinxcontrib-srclinks but that repo is not publically available.

@MantasVaitkunas

This comment has been minimized.

Show comment
Hide comment
@MantasVaitkunas

MantasVaitkunas commented Sep 1, 2015

Added support for sphinx_rtd_theme, maybe someone will find it useful: https://gist.github.com/MantasVaitkunas/7c16de233812adcb7028#file-edit_on_github-py-L38-L43

@QCaudron

This comment has been minimized.

Show comment
Hide comment
@QCaudron

QCaudron May 20, 2016

This is very helpful, thanks. A quick question : line 31 of edit_on_github.py breaks when I make html because doctree is None. Any thoughts on where html_page_context() gets called during build, so I can ensure that the variable is valid ?

Traceback (most recent call last):
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/cmdline.py", line 245, in main
    app.build(opts.force_all, filenames)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 264, in build
    self.builder.build_update()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/__init__.py", line 245, in build_update
    'out of date' % len(to_build))
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/__init__.py", line 319, in build
    self.finish()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 456, in finish
    self.finish_tasks.add_task(self.gen_additional_pages)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/util/parallel.py", line 39, in add_task
    res = task_func()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 482, in gen_additional_pages
    self.handle_page(pagename, context, template)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 781, in handle_page
    templatename, ctx, event_arg)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 501, in emit_firstresult
    for result in self.emit(event, *args):
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 497, in emit
    results.append(callback(self, *args))
  File "/Users/qcaudron/Apps/manatee/docs/_ext/edit_on_github.py", line 30, in html_page_context
    path = os.path.relpath(doctree.get('source'), app.builder.srcdir)
AttributeError: 'NoneType' object has no attribute 'get'

Thanks !

QCaudron commented May 20, 2016

This is very helpful, thanks. A quick question : line 31 of edit_on_github.py breaks when I make html because doctree is None. Any thoughts on where html_page_context() gets called during build, so I can ensure that the variable is valid ?

Traceback (most recent call last):
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/cmdline.py", line 245, in main
    app.build(opts.force_all, filenames)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 264, in build
    self.builder.build_update()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/__init__.py", line 245, in build_update
    'out of date' % len(to_build))
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/__init__.py", line 319, in build
    self.finish()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 456, in finish
    self.finish_tasks.add_task(self.gen_additional_pages)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/util/parallel.py", line 39, in add_task
    res = task_func()
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 482, in gen_additional_pages
    self.handle_page(pagename, context, template)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/builders/html.py", line 781, in handle_page
    templatename, ctx, event_arg)
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 501, in emit_firstresult
    for result in self.emit(event, *args):
  File "/Users/qcaudron/.virtualenvs/market_builder/lib/python3.4/site-packages/sphinx/application.py", line 497, in emit
    results.append(callback(self, *args))
  File "/Users/qcaudron/Apps/manatee/docs/_ext/edit_on_github.py", line 30, in html_page_context
    path = os.path.relpath(doctree.get('source'), app.builder.srcdir)
AttributeError: 'NoneType' object has no attribute 'get'

Thanks !

@tk0miya

This comment has been minimized.

Show comment
Hide comment
@tk0miya

tk0miya 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

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

This comment has been minimized.

Show comment
Hide comment
@sgala

sgala 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

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

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