share/doc/ext/github.py

## Licensed under the Apache License, Version 2.0 (the "License"); you may not
## use this file except in compliance with the License. You may obtain a copy of
## the License at
##
##   http://www.apache.org/licenses/LICENSE-2.0
##
## Unless required by applicable law or agreed to in writing, software
## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
## License for the specific language governing permissions and limitations under
## the License.

import os


def get_github_url(app, view, path):
    return 'https://github.com/{project}/{view}/{branch}/{path}'.format(
        project=app.config.github_project,
        view=view,
        branch=app.config.github_branch,
        path=path)
 
 
def html_page_context(app, pagename, templatename, context, doctree):
    # base template for common sphinx pages like search or genindex
    # there is no need to provide github show/edit links for them
    if templatename != 'page.html':
        return

    # ok, I'm aware about that this is wrong way to concat url segments
    # but this is one is most portable between 2.x and 3.x versions
    # plus it fits our current requirements. But still, patches are welcome (:
    path = os.path.join(
        app.config.github_docs_path,
        os.path.relpath(doctree.get('source'), app.builder.srcdir))
    context['github_show_url'] = get_github_url(app, 'blob', path)
    context['github_edit_url'] = get_github_url(app, 'edit', path)
 
 
def setup(app):
    app.add_config_value('github_project', '', True)
    app.add_config_value('github_branch', 'master', True)
    app.add_config_value('github_docs_path', '', True)
    app.connect('html-page-context', html_page_context)