From 7e5b19639165c25a13eaf7ec8ddc163df31a87f4 Mon Sep 17 00:00:00 2001 From: Noah Watkins Date: Mon, 1 Oct 2018 16:54:19 -0700 Subject: [PATCH] luminous: doc: show edit on github links and version warnings backport of #24452 that adds edit on github links to documentation and notification banners that display warnings when old documentation is being viewed. this is not a cherry-pick: it removes from the original patch the dynamic generation of the releases schedule from a yaml database file. backporting this portion requires modifying the patch to deal with a different file / directory structure [in luminous] with no real added value. Signed-off-by: Noah Watkins Conflicts: doc/conf.py --- doc/README.md | 0 doc/_ext/edit_on_github.py | 43 ++++++++++++++++++++++++++++++++++++++ doc/_static/js/ceph.js | 41 ++++++++++++++++++++++++++++++++++++ doc/_templates/page.html | 21 +++++++++++++++++++ doc/conf.py | 14 +++++++++++++ 5 files changed, 119 insertions(+) create mode 100644 doc/README.md create mode 100644 doc/_ext/edit_on_github.py create mode 100644 doc/_static/js/ceph.js create mode 100644 doc/_templates/page.html diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/doc/_ext/edit_on_github.py b/doc/_ext/edit_on_github.py new file mode 100644 index 0000000000000..290f4b4244d4e --- /dev/null +++ b/doc/_ext/edit_on_github.py @@ -0,0 +1,43 @@ +""" +Adapted from https://gist.github.com/mgedmin/6052926 + +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}/doc/{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) diff --git a/doc/_static/js/ceph.js b/doc/_static/js/ceph.js new file mode 100644 index 0000000000000..61f95fb6ac9e6 --- /dev/null +++ b/doc/_static/js/ceph.js @@ -0,0 +1,41 @@ +$(function() { + var releases_url = "http://docs.ceph.com/docs/master/releases.json"; + + function show_edit(branch, data) { + if (branch) { + if (branch === "master") { + $("#dev-warning").show(); + return true; + } + if (data && data.releases && branch in data.releases) { + var eol = ("actual_eol" in data.releases[branch]); + if (eol) { + $("#eol-warning").show(); + } + return !eol; + } + } + $("#dev-warning").show(); + return false; + } + + function get_branch() { + var url = window.location.href; + var res = url.match(/docs.ceph.com\/docs\/([a-z]+)\/?/i) + if (res) { + return res[1] + } + return null; + } + + $.getJSON(releases_url, function(data) { + var branch = get_branch(); + if (show_edit(branch, data)) { + // patch the edit-on-github URL for correct branch + var url = $("#edit-on-github").attr("href"); + url = url.replace("master", branch); + $("#edit-on-github").attr("href", url); + $("#docubetter").show(); + } + }); +}); diff --git a/doc/_templates/page.html b/doc/_templates/page.html new file mode 100644 index 0000000000000..29cc57f214446 --- /dev/null +++ b/doc/_templates/page.html @@ -0,0 +1,21 @@ +{% extends "!page.html" %} +{% block body %} + + + + + +{%- if edit_on_github_url %} + +{%- endif %} + + {{ super() }} +{% endblock %} diff --git a/doc/conf.py b/doc/conf.py index 42b5d67db9e5f..9c1f4c5a25af4 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,16 +36,20 @@ html_title = "Ceph Documentation" html_logo = 'logo.png' html_favicon = 'favicon.ico' html_show_sphinx = False +html_static_path = ["_static"] html_sidebars = { '**': ['smarttoc.html', 'searchbox.html'], } +sys.path.insert(0, os.path.abspath('_ext')) + extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.graphviz', 'sphinx.ext.todo', 'sphinxcontrib.ditaa', 'breathe', + 'edit_on_github', ] ditaa = 'ditaa' todo_include_todos = True @@ -67,6 +71,16 @@ breathe_projects_source = { } breathe_domain_by_extension = {'py': 'py', 'c': 'c', 'h': 'c', 'cc': 'cxx', 'hpp': 'cxx'} +# the docs are rendered with github links pointing to master. the javascript +# snippet in _static/ceph.js rewrites the edit links when a page is loaded, to +# point to the correct branch. +edit_on_github_project = 'ceph/ceph' +edit_on_github_branch = 'master' + +# handles edit-on-github and old version warning display +def setup(app): + app.add_javascript('js/ceph.js') + # mocking ceph_module offered by ceph-mgr. `ceph_module` is required by # mgr.mgr_module class Dummy(object): -- 2.39.5