Fix source links, display version and warn about outdated docs

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

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

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."]');

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;
 }

config/jsdoc/api/template/tmpl/layout.tmpl

@@ -1,4 +1,3 @@
-<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="utf-8">

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">