Automatically add links to API-docs in examples

When we create the examples, we know exactly which specific `ol.…` symbols
we `goog.require(…)`. We can create links to the API documentation of these
symbols automatically.

config/examples/example.html

@@ -33,6 +33,7 @@
           <p id="shortdesc">{{ shortdesc }}</p>
           <div id="docs">{{ md docs }}</div>
           <div id="tags">{{ tags }}</div>
+          <div id="api-links">Related API documentation: {{{ js.apiHtml }}}</div>
         </div>
       </div>
 

examples/resources/layout.css

@@ -18,6 +18,9 @@ body {
 #tags, #shortdesc, .hidden {
   display: none;
 }
+#api-links ul {
+  display: inline;
+}
 
 body, h1, h2, h3, h4, p, li, td, th {
   font-family: Quattrocento Sans;

tasks/build-examples.js

@@ -8,6 +8,7 @@ var pkg = require('../package.json');
 
 var markupRegEx = /([^\/^\.]*)\.html$/;
 var cleanupJSRegEx = /.*(goog\.require(.*);|.*renderer: common\..*,?)[\n]*/g;
+var googRequiresRegEx = /.*goog\.require\('(ol\.\S*)'\);/g;
 var isCssRegEx = /\.css$/;
 var isJsRegEx = /\.js$/;
 
@@ -15,6 +16,41 @@ var srcDir = path.join(__dirname, '..', 'examples');
 var destDir = path.join(__dirname, '..', 'build', 'examples');
 var templatesDir = path.join(__dirname, '..', 'config', 'examples');
 
+/**
+ * Returns an array of classes that are explicitly required inside the source
+ * by calling 'goog.require(…)'
+ *
+ * @param {string} src The JavaScript sourcecode to search for goog.require.
+ * @returns {Array.<string>} An array of ol-classes that the source requires.
+ */
+function getGoogRequires(src) {
+  var googRequires = [];
+  var match = googRequiresRegEx.exec(src);
+  while (match) {
+    googRequires.push(match[1]);
+    match = googRequiresRegEx.exec(src);
+  }
+  return googRequires;
+}
+
+/**
+ * Takes an array of the names of required OpenLayers symbols and returns an
+ * HTML-snippet with an unordered list to the API-docs for the particular
+ * classes.
+ *
+ * @param {Array.<string>} googRequires An array of ol-classes that the source
+ *   requires.
+ * @returns {string} The HTML-snippet with the list of links to API-docs.
+ */
+function getLinkToApiHtml(googRequires) {
+  var lis = googRequires.map(function(symb) {
+    var href = '../apidoc/' + symb + '.html';
+    return '<li><a href="' + href + '" title="API documentation for ' +
+        symb +'">' + symb + '</a></li>';
+  });
+  return '<ul class="inline">' + lis.join() + '</ul>';
+}
+
 /**
  * A Metalsmith plugin that adds metadata to the example HTML files.  For each
  * example HTML file, this adds metadata for related js and css resources. When
@@ -46,10 +82,11 @@ function augmentExamples(files, metalsmith, done) {
       if (!(jsFilename in files)) {
         throw new Error('No .js file found for ' + filename);
       }
+      var jsSource = files[jsFilename].contents.toString();
       file.js = {
         tag: '<script src="loader.js?id=' + id + '"></script>',
-        source: files[jsFilename].contents.toString().replace(
+        source: jsSource.replace(cleanupJSRegEx, ''),
-            cleanupJSRegEx, '')
+        apiHtml: getLinkToApiHtml(getGoogRequires(jsSource))
       };
 
       // add css tag and source