HOWTO add "Show on GitHub" and "Edit on GitHub" links to the Sphinx sidebar

conf.py.rst

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']

edit_on_github.py

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

sourcelink.html

{%- if show_source and has_source and sourcename %}
  <h3>{{ _('This Page') }}</h3>
  <ul class="this-page-menu">
    <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
           rel="nofollow">{{ _('Show Source') }}</a></li>
  {%- if show_on_github_url %}
    <li><a href="{{ show_on_github_url }}"
           rel="nofollow">{{ _('Show on GitHub') }}</a></li>
  {%- endif %}
  {%- if edit_on_github_url %}
    <li><a href="{{ edit_on_github_url }}"
           rel="nofollow">{{ _('Edit on GitHub') }}</a></li>
  {%- endif %}
  </ul>
{%- endif %}

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 !

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

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

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