From 3274102decb9658923ec2d5977a0ed5d8bd17f91 Mon Sep 17 00:00:00 2001 From: Jonathan Puckey Date: Wed, 1 Jun 2011 12:19:15 +0200 Subject: [PATCH] More jsdoc work, including exporting of templatedocs. --- build/docs.sh | 15 +++++- .../conf/{paperjs.conf => docs.conf} | 5 +- build/jsdoc-toolkit/conf/templatedocs.conf | 33 ++++++++++++ .../templates/jsdoc/classorder.txt | 29 ---------- .../jsdoc-toolkit/templates/jsdoc/publish.js | 53 +++++++++++++------ .../templates/jsdoc/templates/class.tmpl | 47 ++++++++-------- .../jsdoc/templates/constructor.tmpl | 12 ++--- 7 files changed, 117 insertions(+), 77 deletions(-) rename build/jsdoc-toolkit/conf/{paperjs.conf => docs.conf} (91%) create mode 100644 build/jsdoc-toolkit/conf/templatedocs.conf delete mode 100644 build/jsdoc-toolkit/templates/jsdoc/classorder.txt diff --git a/build/docs.sh b/build/docs.sh index b74f12d7..c863344f 100755 --- a/build/docs.sh +++ b/build/docs.sh @@ -10,7 +10,18 @@ # All rights reserved. See LICENSE file for details. # Generate documentation +# +# MODE: +# docs Generates the JS API docs +# templatedocs Generates the website templates for the online JS API docs + +if [ $# -eq 0 ] +then + MODE="docs" +else + MODE=$1 +fi cd jsdoc-toolkit -java -jar jsrun.jar app/run.js -c=conf/paperjs.conf -cd .. +java -jar jsrun.jar app/run.js -c=conf/$MODE.conf +cd .. \ No newline at end of file diff --git a/build/jsdoc-toolkit/conf/paperjs.conf b/build/jsdoc-toolkit/conf/docs.conf similarity index 91% rename from build/jsdoc-toolkit/conf/paperjs.conf rename to build/jsdoc-toolkit/conf/docs.conf index c677f6ac..076fd6b5 100644 --- a/build/jsdoc-toolkit/conf/paperjs.conf +++ b/build/jsdoc-toolkit/conf/docs.conf @@ -26,5 +26,8 @@ d: "../../out/docs", // use this template - t: "templates/jsdoc" + t: "templates/jsdoc", + + // set variables: + D: "renderMode:docs" } \ No newline at end of file diff --git a/build/jsdoc-toolkit/conf/templatedocs.conf b/build/jsdoc-toolkit/conf/templatedocs.conf new file mode 100644 index 00000000..7b0e723d --- /dev/null +++ b/build/jsdoc-toolkit/conf/templatedocs.conf @@ -0,0 +1,33 @@ +/* + This is an example of one way you could set up a configuration file to more + conveniently define some commandline options. You might like to do this if + you frequently reuse the same options. Note that you don't need to define + every option in this file, you can combine a configuration file with + additional options on the commandline if your wish. + + You would include this configuration file by running JsDoc Toolkit like so: + java -jar jsrun.jar app/run.js -c=conf/sample.conf + +*/ + +{ + // source files to use + _: ['../../src'], + + r: 2, + + // document all functions, even uncommented ones + a: false, + + // including those marked @private + p: false, + + // use this directory as the output directory + d: "../../out/templates", + + // use this template + t: "templates/jsdoc", + + // set variables: + D: "renderMode:templatedocs" +} \ No newline at end of file diff --git a/build/jsdoc-toolkit/templates/jsdoc/classorder.txt b/build/jsdoc-toolkit/templates/jsdoc/classorder.txt deleted file mode 100644 index 876b415e..00000000 --- a/build/jsdoc-toolkit/templates/jsdoc/classorder.txt +++ /dev/null @@ -1,29 +0,0 @@ -Point -Rectangle -Size -Matrix -Color - GrayColor - RGBColor - GradientColor -Item - PathItem - Path - CompoundPath - TextItem - PointText - Raster - Group - Layer - PlacedItem - Symbol -Project -ProjectView -Segment -Curve -PathStyle - CharacterStyle -ParagraphStyle -Gradient -GradientStop -Symbol diff --git a/build/jsdoc-toolkit/templates/jsdoc/publish.js b/build/jsdoc-toolkit/templates/jsdoc/publish.js index 56fb3f3f..d7c05d45 100644 --- a/build/jsdoc-toolkit/templates/jsdoc/publish.js +++ b/build/jsdoc-toolkit/templates/jsdoc/publish.js @@ -1,14 +1,16 @@ /** Called automatically by JsDoc Toolkit. */ function publish(symbolSet) { + var renderMode = JSDOC.opt.D.renderMode; publish.conf = { // trailing slash expected for dirs - ext: '.html', + ext: renderMode == 'docs' ? '.html' : '.jstl', outDir: JSDOC.opt.d || SYS.pwd + '../out/jsdoc/', templateDir: JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/', staticDir: (JSDOC.opt.t || SYS.pwd + '../templates/jsdoc/') + 'static/', - symbolsDir: 'packages/', - srcDir: 'symbols/src/' + symbolsDir: renderMode == 'docs' ? 'packages/' : 'paper/', + srcDir: 'symbols/src/', + renderMode: renderMode }; - publish.conf.packagesDir = publish.conf.outDir + 'packages/'; + publish.conf.packagesDir = publish.conf.outDir + publish.conf.symbolsDir; var templatesDir = publish.conf.templateDir + 'templates/'; publish.templates = { _class: 'class.tmpl', @@ -29,12 +31,17 @@ function publish(symbolSet) { publish.templates[i] = new JSDOC.JsPlate(templatesDir + publish.templates[i]); } - - // Copy over the static files - Utils.copyDirectory( - new java.io.File(publish.conf.staticDir), - new java.io.File(publish.conf.outDir) - ); + + if (renderMode == 'docs') { + // Copy over the static files + Utils.copyDirectory( + new java.io.File(publish.conf.staticDir), + new java.io.File(publish.conf.outDir) + ); + } else { + Utils.deleteFiles(new File(publish.conf.outDir)); + new java.io.File(publish.conf.outDir + 'paper/').mkdirs(); + } // used to allow Link to check the details of things being linked to Link.symbolSet = symbolSet; @@ -77,16 +84,19 @@ function publish(symbolSet) { } Link.currentSymbol= symbol; - var html = publish.templates.html.process({ - content: publish.templates._class.process(symbol), - title: symbol.alias - }); + var html = publish.templates._class.process(symbol); var name = ((JSDOC.opt.u)? Link.filemap[symbol.alias] : symbol.alias) + publish.conf.ext; + if (renderMode == 'docs') { + html = publish.templates.html.process({ + content: html, + title: symbol.alias + }); + } IO.saveFile(publish.conf.packagesDir, name, html); } - - Utils.publishMenu(); + if (renderMode == 'docs') + Utils.publishMenu(); } var Operator = new function() { @@ -195,6 +205,17 @@ var Utils = { } }, + deleteFiles: function(path) { + if (path.isDirectory()) { + var files = path.listFiles(); + for (var i = 0, l = files.length; i < l; i++) { + Utils.deleteFiles(files[i]); + } + } + if (!path['delete']()) + throw Error('Could not delete ' + path); + }, + processGroupTitle: function(str, symbol) { var groupTitle = str.match(/\{@grouptitle ([^}]+)\}/); if (groupTitle) { diff --git a/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl b/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl index 70861edd..16b92834 100644 --- a/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl +++ b/build/jsdoc-toolkit/templates/jsdoc/templates/class.tmpl @@ -1,5 +1,5 @@ -{! data.classId = data.alias.toLowerCase() !} {! + data.classId = data.alias.toLowerCase(); var constructors = data.methods.filter(function($){return $.memberOf == data.alias && $.isConstructor}); var ownProperties = data.properties.filter(function($){return $.memberOf == data.alias && !$.isNamespace && !$.isStatic && !$.isConstructor}); var staticProperties = data.properties.filter(function($){return $.memberOf == data.alias && !$.isNamespace && $.isStatic && !$.isConstructor}); @@ -43,14 +43,14 @@ } !}
-

{+data.alias+}

+

{+data.alias+}

Extends {+ inheritedClassLinks.join(', ') +}

 {+Utils.processInlineTags(data.classDesc)+}
- +

Constructors

{+ publish.templates.constructor.process(data) +} @@ -59,8 +59,8 @@
- +

Operators

{+ publish.templates.operators.process(member) +} @@ -76,8 +76,8 @@
- +

Functions

{+ publish.templates.method.process(member) +} @@ -92,21 +92,24 @@
- - -

Properties inherited from {+ new Link().toSymbol(inheritedClass.className) +}

- - {+ publish.templates.property.process(member) +} - -
- - - -

Functions inherited from {+ new Link().toSymbol(inheritedClass.className) +}

- - {+ publish.templates.method.process(member) +} - -
- + + +

Properties inherited from {+ new Link().toSymbol(inheritedClass.className) +}

+ + {+ publish.templates.property.process(member) +} -

Copyright © 21011 Jürg Lehni & Jonathan Puckey. All Rights Reserved.

\ No newline at end of file +
+ + + +

Functions inherited from {+ new Link().toSymbol(inheritedClass.className) +}

+ + {+ publish.templates.method.process(member) +} + +
+ + + + +

Copyright © 21011 Jürg Lehni & Jonathan Puckey. All Rights Reserved.

+ \ No newline at end of file diff --git a/build/jsdoc-toolkit/templates/jsdoc/templates/constructor.tmpl b/build/jsdoc-toolkit/templates/jsdoc/templates/constructor.tmpl index 408e09f3..917ed317 100644 --- a/build/jsdoc-toolkit/templates/jsdoc/templates/constructor.tmpl +++ b/build/jsdoc-toolkit/templates/jsdoc/templates/constructor.tmpl @@ -5,9 +5,7 @@ if (data.returns.length == 0) data.returns = [{type: data.memberOf ? data.memberOf : data.alias, desc: ''}]; !} - -

{+data.groupTitle+}

- +

{+data.groupTitle+}
{+Utils.processInlineTags(data.desc)+} - {+ publish.templates.parameters.process(data) +} - {+ publish.templates.returns.process(data) +} - {+ Utils.parseExamples(data) +} - {+ publish.templates.seeAlsos.process(data) +} +{+ publish.templates.parameters.process(data) +} +{+ publish.templates.returns.process(data) +} +{+ Utils.parseExamples(data) +} +{+ publish.templates.seeAlsos.process(data) +}