Broken "Edit on Github" links

[coldfix]

Hey,

some themes like sphinx_rtd_theme emit "Edit on GitHub" links to the page source in the git repository. For autogenerated pages this link points to something that doesn't exist, i.e. using such a theme with autogenerated modules often results in invalid links in the documentation.

I've seen this issue several times in the wild now, so I believe many would profit from a better default handling of this situation, or at least some prominent documentation. It's of course arguable whether the fix should go here or into the theme code. This issue was also raised in https://github.com/readthedocs/sphinx_rtd_theme/issues/324 and their resolution (see https://github.com/readthedocs/sphinx_rtd_theme/pull/393) was to simply use sphinx's hasdoc() function to check whether the current page refers to a physical (vs autogenerated) document. A can't comment on whether their interpretation of the purpose of hasdoc is correct since there is very little documentation on it, but that's the status quo.

The relevant section in sphinx_rtd_theme's page generation template checks for hasdoc(page) and display_github.

A user can therefore fix this problem in their conf.py by setting display_github = False for automod generated pages like this:

def setup(app):
    app.connect("html-page-context", html_page_context)


def html_page_context(app, pagename, templatename, context, doctree):
    """Avoid broken source links to auto-generated API-docs."""
    if pagename.startswith('automod/'):
        context['display_github'] = False
        context['meta'] = None

The context['meta'] = None assignment is needed to prevent an automatic setting of display_github = True.

Alternatively, one could override hasdoc similar to this (untested):

def html_page_context(app, pagename, templatename, context, doctree):
    """Avoid broken source links to auto-generated API-docs."""
    orig_hasdoc = context['hasdoc']
    context['hasdoc'] = lambda name: orig_hasdoc(name) and not name.startswith('automod/') 

So possible fixes in sphinx-automodapi could amount to one of:

• add one of the above snippets to the documentation
• include equivalent of one of the above snippets in setup code
• make hasdoc() return False by preventing autogenerated pages from being included in Builder.env.all_docs (see first line of hasdoc)