diff --git a/build.py b/build.py index 28193907f4..1659dab6ab 100755 --- a/build.py +++ b/build.py @@ -480,11 +480,11 @@ def gh_pages(t): virtual('doc', 'build/jsdoc-%(BRANCH)s-timestamp' % vars(variables)) -@target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), SRC, SHADER_SRC, - ifind('doc/template')) +@target('build/jsdoc-%(BRANCH)s-timestamp' % vars(variables), 'host-resources', + 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() @@ -520,7 +520,13 @@ def split_example_file(example, dst_dir): target_require.close() -@target('host-examples', 'build', 'examples', phony=True) +@target('host-resources', phony=True) +def host_resources(t): + resources_dir = 'build/gh-pages/%(BRANCH)s/resources' + t.rm_rf(resources_dir); + t.cp_r('resources', resources_dir); + +@target('host-examples', 'build', 'host-resources', 'examples', phony=True) def host_examples(t): examples_dir = 'build/gh-pages/%(BRANCH)s/examples' build_dir = 'build/gh-pages/%(BRANCH)s/build' @@ -528,18 +534,15 @@ def host_examples(t): t.makedirs(examples_dir) t.rm_rf(build_dir) t.makedirs(build_dir) - t.cp(EXAMPLES, 'examples/examples.css', examples_dir) + t.cp(EXAMPLES, examples_dir) for example in [path.replace('.html', '.js') for path in EXAMPLES]: split_example_file(example, examples_dir % vars(variables)) - t.cp_r('examples/data', examples_dir + '/data') - t.cp_r('examples/bootstrap', examples_dir + '/bootstrap') - t.cp_r('examples/font-awesome', examples_dir + '/font-awesome') t.cp('bin/loader_hosted_examples.js', examples_dir + '/loader.js') t.cp('build/ol.js', 'build/ol-simple.js', 'build/ol-whitespace.js', 'build/ol.css', build_dir) t.cp('examples/index.html', 'examples/example-list.js', 'examples/example-list.xml', 'examples/Jugl.js', - 'examples/jquery.min.js', 'examples/social-links.js', examples_dir) + 'examples/jquery.min.js', examples_dir) t.rm_rf('build/gh-pages/%(BRANCH)s/closure-library') t.makedirs('build/gh-pages/%(BRANCH)s/closure-library') with t.chdir('build/gh-pages/%(BRANCH)s/closure-library'): 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/jsdoc-default.css b/doc/template/static/styles/jsdoc-default.css index 47b2756c09..56bbb5b4e4 100644 --- a/doc/template/static/styles/jsdoc-default.css +++ b/doc/template/static/styles/jsdoc-default.css @@ -203,7 +203,7 @@ dt.tag-source, dd.tag-source { } .details { margin-top: 14px; } -.details dt { width:100px; float:left; border-left: 2px solid #DDD; padding-left: 10px; padding-top: 6px; } +.details dt { width:110px; float:left; border-left: 2px solid #DDD; padding-left: 10px; padding-top: 6px; } .details dd { margin-left: 50px; } .details ul { margin: 0; } .details ul { list-style-type: none; } 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/layout.tmpl b/doc/template/tmpl/layout.tmpl index 91857f98e7..f073122964 100644 --- a/doc/template/tmpl/layout.tmpl +++ b/doc/template/tmpl/layout.tmpl @@ -2,7 +2,7 @@ - OpenLayers: <?js= title ?> + OpenLayers 3 API Documentation - <?js= title ?> @@ -11,14 +11,29 @@ + + + -
- -

- +
+
+
+ OpenLayers 3 API Documentation - +
    +
    • +
    • +
    • +
+
+
+
+ +
+
@@ -31,7 +46,9 @@
Documentation generated by JSDoc 3 on
+
+ 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/examples/animation.html b/examples/animation.html index d1b3b285b0..621cb47721 100644 --- a/examples/animation.html +++ b/examples/animation.html @@ -4,9 +4,9 @@ - - - + + + Animation example @@ -57,7 +57,7 @@
- + diff --git a/examples/bind-input.html b/examples/bind-input.html index 7e09555b42..5d92ad2e6f 100644 --- a/examples/bind-input.html +++ b/examples/bind-input.html @@ -4,9 +4,9 @@ - - - + + + Bind HTML input example @@ -81,7 +81,7 @@ - + diff --git a/examples/bing-maps.html b/examples/bing-maps.html index 1fd6bf8dcc..547857c290 100644 --- a/examples/bing-maps.html +++ b/examples/bing-maps.html @@ -4,9 +4,9 @@ - - - + + + Bing Maps example @@ -56,7 +56,7 @@ - + diff --git a/examples/brightness-contrast.html b/examples/brightness-contrast.html index 67542e5591..c4ac127ebf 100644 --- a/examples/brightness-contrast.html +++ b/examples/brightness-contrast.html @@ -4,9 +4,9 @@ - - - + + + Brightness/contrast example @@ -59,7 +59,7 @@ - + diff --git a/examples/canvas-tiles.html b/examples/canvas-tiles.html index a8eb159133..bd9290a6f4 100644 --- a/examples/canvas-tiles.html +++ b/examples/canvas-tiles.html @@ -4,9 +4,9 @@ - - - + + + Canvas tiles example @@ -49,7 +49,7 @@ - + diff --git a/examples/epsg-4326.html b/examples/epsg-4326.html index f50838cb1e..33be85967a 100644 --- a/examples/epsg-4326.html +++ b/examples/epsg-4326.html @@ -4,9 +4,9 @@ - - - + + + EPSG:4326 example @@ -49,7 +49,7 @@ - + diff --git a/examples/export-map.html b/examples/export-map.html index 1950b88614..759bba20b5 100644 --- a/examples/export-map.html +++ b/examples/export-map.html @@ -4,9 +4,9 @@ - - - + + + Export map example @@ -51,7 +51,7 @@ - + diff --git a/examples/geolocation.html b/examples/geolocation.html index 597b14e7ce..09e4243a16 100644 --- a/examples/geolocation.html +++ b/examples/geolocation.html @@ -4,9 +4,9 @@ - - - + + +