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 <nwatkins@redhat.com>

diff --git a/doc/README.md b/doc/README.md
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/doc/_ext/edit_on_github.py b/doc/_ext/edit_on_github.py
new file mode 100644 (file)
index 0000000..290f4b4
--- /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 (file)
index 0000000..61f95fb
--- /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 (file)
index 0000000..29cc57f
--- /dev/null
+++ b/doc/_templates/page.html
@@ -0,0 +1,21 @@
+{% extends "!page.html" %}
+{% block body %}
+
+<div id="dev-warning" class="admonition note" style="display:none;">
+  <p class="first admonition-title">Notice</p>
+  <p class="last">This document is for a development version of Ceph.</p>
+</div>
+
+<div id="eol-warning" class="admonition warning" style="display:none;">
+  <p class="first admonition-title">Warning</p>
+  <p class="last">This document is for an unsupported version of Ceph.</p>
+</div>
+
+{%- if edit_on_github_url %}
+  <div id="docubetter" align="right" style="display:none; padding: 15px; font-weight: bold;">
+    <a id="edit-on-github" href="{{ edit_on_github_url }}" rel="nofollow">{{ _('Edit on GitHub')}}</a>
+  </div>
+{%- endif %}
+
+  {{ super() }}
+{% endblock %}

diff --git a/doc/conf.py b/doc/conf.py
index ce1e5af9754f8a8cd0742726c55a11e15f4f915a..6bd56ba40075fbd0eae949f40c9da172266ac137 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -33,16 +33,20 @@ html_logo = 'logo.png'
 html_favicon = 'favicon.ico'
 html_use_smartypants = True
 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
@@ -66,3 +70,13 @@ breathe_domain_by_extension = {'py': 'py', 'c': 'c', 'h': 'c', 'cc': 'cxx', 'hpp
 pybind = os.path.join(top_level, 'src/pybind')
 if pybind not in sys.path:
     sys.path.insert(0, pybind)
+
+# 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')