Enabling Markdown and other JSDoc improvements

This change enables GitHub flavored markdown for APIdoc
comments. The code example in map.js shows how to use markdown
for code snippets. doc/index.md is now included again as start
page for the docs. Everything in the doc/tutorials directory
will also be added to the docs as tutorial. As an example, I
moved the ol3.md file with the architecture to the tutorials
directory.

Currently properties and methods annotated with @inheritDoc
or @override won't be documented at all. This is a known issue,
so I added a custom JSDoc plugin with a hack to avoid this.

build.py

@@ -436,8 +436,8 @@ virtual('doc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables))
 @target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), SRC, SHADER_SRC,
         ifind('doc/template'))
 def jsdoc_BRANCH_timestamp(t):
-    t.run('%(JSDOC)s', '-t', 'doc/template', '-r',
+    t.run('%(JSDOC)s', '-c', 'doc/conf.json', 'src', 'doc/index.md',
-          'src', '-d', 'build/gh-pages/%(BRANCH)s/apidoc')
+          '-d', 'build/gh-pages/%(BRANCH)s/apidoc')
     t.touch()
 
 

doc/conf.json

@@ -0,0 +1,26 @@
+{
+    "opts": {
+        "recurse": true,
+        "template": "doc/template",
+        "tutorials": "doc/tutorials"
+    },
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "plugins": [ "plugins/markdown", "doc/plugins/inheritdoc" ],
+    "markdown": {
+        "parser": "gfm"
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false,
+        "default": {
+            "outputSourceFiles": true
+        }
+    },
+    "jsVersion": 180
+}

doc/plugins/inheritdoc.js

@@ -0,0 +1,16 @@
+/*
+ * This is a hack to prevent inheritDoc and override tags from entirely removing
+ * documentation of the method that inherits the documentation.
+ *
+ * TODO: Remove this hack when https://github.com/jsdoc3/jsdoc/issues/53
+ * is addressed.
+ */
+exports.handlers = {
+
+  beforeParse: function(e) {
+    e.source = e.source.replace(
+        /\/\*\*\r?\n?\s*\* @(inheritDoc|override)\r?\n?\s*\*\/\r?\n?/g,
+        "/***\n *\n */\n");
+  }
+
+};

doc/template/publish.js

@@ -180,7 +180,7 @@ function buildNav(members) {
     if (members.tutorials.length) {
         nav += '<h3>Tutorials</h3><ul>';
         members.tutorials.sort(byLongName).forEach(function(t) {
-            nav += '<li>'+tutoriallink(t.longname)+'</li>';
+            nav += '<li>'+tutoriallink(t.name)+'</li>';
         });
         
         nav += '</ul>';

doc/template/static/styles/prettify-tomorrow.css

@@ -0,0 +1,132 @@
+/* Tomorrow Theme */
+/* Original theme - https://github.com/chriskempson/tomorrow-theme */
+/* Pretty printing styles. Used with prettify.js. */
+/* SPAN elements with the classes below are added by prettyprint. */
+/* plain text */
+.pln {
+  color: #4d4d4c; }
+
+@media screen {
+  /* string content */
+  .str {
+    color: #718c00; }
+
+  /* a keyword */
+  .kwd {
+    color: #8959a8; }
+
+  /* a comment */
+  .com {
+    color: #8e908c; }
+
+  /* a type name */
+  .typ {
+    color: #4271ae; }
+
+  /* a literal value */
+  .lit {
+    color: #f5871f; }
+
+  /* punctuation */
+  .pun {
+    color: #4d4d4c; }
+
+  /* lisp open bracket */
+  .opn {
+    color: #4d4d4c; }
+
+  /* lisp close bracket */
+  .clo {
+    color: #4d4d4c; }
+
+  /* a markup tag name */
+  .tag {
+    color: #c82829; }
+
+  /* a markup attribute name */
+  .atn {
+    color: #f5871f; }
+
+  /* a markup attribute value */
+  .atv {
+    color: #3e999f; }
+
+  /* a declaration */
+  .dec {
+    color: #f5871f; }
+
+  /* a variable name */
+  .var {
+    color: #c82829; }
+
+  /* a function name */
+  .fun {
+    color: #4271ae; } }
+/* Use higher contrast and text-weight for printable form. */
+@media print, projection {
+  .str {
+    color: #060; }
+
+  .kwd {
+    color: #006;
+    font-weight: bold; }
+
+  .com {
+    color: #600;
+    font-style: italic; }
+
+  .typ {
+    color: #404;
+    font-weight: bold; }
+
+  .lit {
+    color: #044; }
+
+  .pun, .opn, .clo {
+    color: #440; }
+
+  .tag {
+    color: #006;
+    font-weight: bold; }
+
+  .atn {
+    color: #404; }
+
+  .atv {
+    color: #060; } }
+/* Style */
+/*
+pre.prettyprint {
+  background: white;
+  font-family: Menlo, Monaco, Consolas, monospace;
+  font-size: 12px;
+  line-height: 1.5;
+  border: 1px solid #ccc;
+  padding: 10px; }
+*/
+
+/* Specify class=linenums on a pre to get line numbering */
+ol.linenums {
+  margin-top: 0;
+  margin-bottom: 0; }
+
+/* IE indents via margin-left */
+li.L0,
+li.L1,
+li.L2,
+li.L3,
+li.L4,
+li.L5,
+li.L6,
+li.L7,
+li.L8,
+li.L9 {
+  /* */ }
+
+/* Alternate shading for lines */
+li.L1,
+li.L3,
+li.L5,
+li.L7,
+li.L9 {
+  /* */ }

doc/template/tmpl/source.tmpl

@@ -0,0 +1,8 @@
+<?js
+    var data = obj;
+?>
+    <section>
+        <article>
+            <pre class="prettyprint source"><code><?js= data.code ?></code></pre>
+        </article>
+    </section>

doc/tutorials/ol3.json

@@ -0,0 +1,3 @@
+{
+    "title": "OpenLayers 3 Architecture"
+}

src/ol/map.js

@@ -110,6 +110,26 @@ ol.MapProperty = {
 
 
 /**
+ * @class
+ * The map is the core component of OpenLayers. In its minimal configuration it
+ * needs a view, one or more layers, and a target container:
+ *
+ *     var map = new ol.Map({
+ *       view: new ol.View2D({
+ *         center: new ol.Coordinate(0, 0),
+ *         zoom: 1
+ *       }),
+ *       layers: [
+ *         new ol.layer.TileLayer({
+ *           source: new ol.source.MapQuestOSM()
+ *         })
+ *       ],
+ *       target: 'map'
+ *     });
+ *
+ * The above snippet creates a map with a MapQuest OSM layer on a 2D view and
+ * renders it to a DOM element with the id 'map'.
+ *
  * @constructor
  * @extends {ol.Object}
  * @param {ol.MapOptions} mapOptions Map options.