diff --git a/build.py b/build.py index ed4fa20ef9..a8d8b68b45 100755 --- a/build.py +++ b/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', - 'src', '-d', 'build/gh-pages/%(BRANCH)s/apidoc') + t.run('%(JSDOC)s', '-c', 'doc/conf.json', 'src', 'doc/index.md', + '-d', 'build/gh-pages/%(BRANCH)s/apidoc') t.touch() diff --git a/doc/conf.json b/doc/conf.json new file mode 100644 index 0000000000..986a90ec61 --- /dev/null +++ b/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 +} diff --git a/doc/plugins/inheritdoc.js b/doc/plugins/inheritdoc.js new file mode 100644 index 0000000000..56f9a48d71 --- /dev/null +++ b/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"); + } + +}; \ No newline at end of file diff --git a/doc/template/publish.js b/doc/template/publish.js index dbea28edb7..cb26529918 100644 --- a/doc/template/publish.js +++ b/doc/template/publish.js @@ -180,7 +180,7 @@ function buildNav(members) { if (members.tutorials.length) { nav += '

Tutorials

'; diff --git a/doc/template/static/styles/prettify-tomorrow.css b/doc/template/static/styles/prettify-tomorrow.css new file mode 100644 index 0000000000..aa2908c251 --- /dev/null +++ b/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 { + /* */ } diff --git a/doc/template/tmpl/source.tmpl b/doc/template/tmpl/source.tmpl new file mode 100644 index 0000000000..e1092ef297 --- /dev/null +++ b/doc/template/tmpl/source.tmpl @@ -0,0 +1,8 @@ + +
+
+
+
+
\ No newline at end of file diff --git a/doc/tutorials/ol3.json b/doc/tutorials/ol3.json new file mode 100644 index 0000000000..f0c33cdb2b --- /dev/null +++ b/doc/tutorials/ol3.json @@ -0,0 +1,3 @@ +{ + "title": "OpenLayers 3 Architecture" +} diff --git a/doc/ol3.md b/doc/tutorials/ol3.md similarity index 100% rename from doc/ol3.md rename to doc/tutorials/ol3.md diff --git a/src/ol/map.js b/src/ol/map.js index c616c64669..379a65d297 100644 --- a/src/ol/map.js +++ b/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.