Merge pull request #3551 from marcjansen/examples-link-to-api-docs

Automatically add links to API-docs in examples

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/common.js

@@ -10,6 +10,31 @@
     });
   }
 
+  // Check whether links to API-docs of used classes actually point to
+  // existing html-files:
+  $('#api-links a').each(function() {
+    var url = this.href;
+    $.ajax({
+      type: 'HEAD',
+      url: url,
+      context: this,
+      error: function() {
+        // We get into the error if either the resource didn't exist
+        // or if HEAD was not allowed (when serving locally via node)
+        // => remove the <li> and the following comma
+        var li = $(this).parent();
+        var comma = $(li[0].nextSibling);
+        comma.remove();
+        li.remove();
+        // It may be that this was the last <li>, if that's the case,
+        // remove the complete <div>, as we don't have an API-links
+        if ($('#api-links li').length === 0) {
+          $('#api-links').remove();
+        }
+      }
+    });
+  });
+
   if (window.location.host === 'localhost:3000') {
     return;
   }

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