From d27ea0974ee5489ff1ca5b186b3bd7b13013314f Mon Sep 17 00:00:00 2001
From: Andreas Hocevar <andreas.hocevar@gmail.com>
Date: Tue, 10 May 2016 17:09:07 +0200
Subject: [PATCH] Fix source links, display version and warn about outdated
 docs

---
 Makefile                                      |  2 +-
 config/jsdoc/api/template/publish.js          | 15 +++-----
 .../jsdoc/api/template/static/scripts/main.js | 35 +++++++++++++------
 .../api/template/static/styles/jaguar.css     |  1 +
 config/jsdoc/api/template/tmpl/layout.tmpl    |  1 -
 .../jsdoc/api/template/tmpl/navigation.tmpl   |  3 +-
 6 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/Makefile b/Makefile
index 33683ba16a..fe150e5bf3 100644
--- a/Makefile
+++ b/Makefile
@@ -211,7 +211,7 @@ build/timestamps/jsdoc-$(BRANCH)-timestamp: config/jsdoc/api/index.md \
                                             build/timestamps/node-modules-timestamp
 	@mkdir -p $(@D)
 	@rm -rf $(BUILD_HOSTED)/apidoc
-	./node_modules/.bin/jsdoc config/jsdoc/api/index.md -c config/jsdoc/api/conf.json -d $(BUILD_HOSTED)/apidoc
+	./node_modules/.bin/jsdoc config/jsdoc/api/index.md -c config/jsdoc/api/conf.json --package package.json -d $(BUILD_HOSTED)/apidoc
 	@touch $@
 
 $(BUILD_HOSTED_EXAMPLES_JS): $(BUILD_HOSTED)/examples/%.js: build/examples/%.js
diff --git a/config/jsdoc/api/template/publish.js b/config/jsdoc/api/template/publish.js
index 1a0ca87840..c98be1de77 100644
--- a/config/jsdoc/api/template/publish.js
+++ b/config/jsdoc/api/template/publish.js
@@ -113,7 +113,8 @@ function generate(title, docs, filename, resolveLinks) {
     var docData = {
         filename: filename,
         title: title,
-        docs: docs
+        docs: docs,
+        packageInfo: ( find({kind: 'package'}) || [] ) [0]
     };
 
     var outpath = path.join(outdir, filename),
@@ -327,11 +328,6 @@ exports.publish = function(taffyData, opts, tutorials) {
         }
     });
 
-    // update outdir if necessary, then create outdir
-    var packageInfo = ( find({kind: 'package'}) || [] ) [0];
-    if (packageInfo && packageInfo.name) {
-        outdir = path.join(outdir, packageInfo.name, packageInfo.version);
-    }
     fs.mkPath(outdir);
 
     // copy the template's static files to outdir
@@ -439,13 +435,10 @@ exports.publish = function(taffyData, opts, tutorials) {
     if (members.globals.length) { generate('Global', [{kind: 'globalobj'}], globalUrl); }
 
     // index page displays information from package.json and lists files
-    var files = find({kind: 'file'}),
-        packages = find({kind: 'package'});
+    var files = find({kind: 'file'});
 
     generate('Index',
-        packages.concat(
-            [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}]
-        ).concat(files),
+        [{kind: 'mainpage', readme: opts.readme, longname: (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}].concat(files),
     indexUrl);
 
     // set up the lists that we'll use to generate pages
diff --git a/config/jsdoc/api/template/static/scripts/main.js b/config/jsdoc/api/template/static/scripts/main.js
index 30113d8f64..21158ecd74 100644
--- a/config/jsdoc/api/template/static/scripts/main.js
+++ b/config/jsdoc/api/template/static/scripts/main.js
@@ -55,18 +55,31 @@ $(function () {
 
     // create source code links to github
     var srcLinks = $('div.tag-source');
-    var masterSearch = window.location.href.match(/\/([^\/]*\/)apidoc\//);
-    if (masterSearch && masterSearch.length) {
-      var branch = masterSearch[1];
-      srcLinks.each(function(i, el) {
-        var textParts = el.innerHTML.trim().split(', ');
-        var link = 'https://github.com/openlayers/ol3/blob/' + branch +
-            textParts[0];
-        el.innerHTML = '<a href="' + link + '">' + textParts[0] + '</a>, ' +
-            '<a href="' + link + textParts[1].replace('line ', '#l') + '">' +
-            textParts[1] + '</a>';
-      });
+    var location = window.location.href;
+    var branchSearch = location.match(/\/([^\/]*)\/apidoc\//);
+    if (branchSearch && branchSearch.length) {
+      var branch = branchSearch[1];
+      if (branch !== 'latest') {
+        if (/^v[0-9\.]*$/.test(branch)) {
+          var ok = confirm('You are viewing outdated docs. Do you want to try the latest?');
+          if (ok) {
+            window.location.href = location.replace(branchSearch[0], '/latest/apidoc/');
+          }
+        } else {
+          $('.package-version').text(branch);
+        }
+      }
     }
+    var version = $('.package-version');
+    var branch = version.text();
+    srcLinks.each(function(i, el) {
+      var textParts = el.innerHTML.trim().split(', ');
+      var link = 'https://github.com/openlayers/ol3/blob/' + branch + '/' +
+          textParts[0];
+      el.innerHTML = '<a href="' + link + '">' + textParts[0] + '</a>, ' +
+          '<a href="' + link + textParts[1].replace('line ', '#l') + '">' +
+          textParts[1] + '</a>';
+    });
 
     // show/hide unstable items
     var links = $('a[href^="ol."]');
diff --git a/config/jsdoc/api/template/static/styles/jaguar.css b/config/jsdoc/api/template/static/styles/jaguar.css
index 0c3493d21f..fa2e7df197 100644
--- a/config/jsdoc/api/template/static/styles/jaguar.css
+++ b/config/jsdoc/api/template/static/styles/jaguar.css
@@ -132,6 +132,7 @@ li {
   display: block;
   font-size: 0.85em;
 }
+.navigation h4,
 .navigation li.item .title a {
   color: #e1e1e1;
 }
diff --git a/config/jsdoc/api/template/tmpl/layout.tmpl b/config/jsdoc/api/template/tmpl/layout.tmpl
index 613caf095e..1d108d413f 100644
--- a/config/jsdoc/api/template/tmpl/layout.tmpl
+++ b/config/jsdoc/api/template/tmpl/layout.tmpl
@@ -1,4 +1,3 @@
-<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="utf-8">
diff --git a/config/jsdoc/api/template/tmpl/navigation.tmpl b/config/jsdoc/api/template/tmpl/navigation.tmpl
index 7a41bfed9b..6972914432 100644
--- a/config/jsdoc/api/template/tmpl/navigation.tmpl
+++ b/config/jsdoc/api/template/tmpl/navigation.tmpl
@@ -3,6 +3,7 @@ var self = this;
 ?>
 <div class="navigation">
     <div class="search">
+        <h4 class='package-version'>v<?js= self.version ?></h4>
         <input id="search" type="text" class="form-control input-sm" placeholder="Search Documentation">
     </div>
     <ul class="list">
@@ -84,4 +85,4 @@ var self = this;
         </li>
     <?js }); ?>
     </ul>
-</div>
\ No newline at end of file
+</div>