PIXI-in-Docs - Initial

- Initial support for generating PIXI-combined documentation
- Includes yuidoc-to-jsdoc for generating pixi-jsdoc.js
- Creates doc (using pixidoc + builddoc) tasks
- Adds sourceproxy JSDoc plugin to map in corrected file/line meta
- Added yuidocjs as a dev-dependency

Author: pnstickne

docs/build/conf.json

@@ -4,6 +4,7 @@
     },
     "source": {
         "include": [ 
+            "../pixi-jsdoc.js",
             "../../src/Phaser.js", 
             "../../src/animation/", 
             "../../src/core/", 
@@ -30,6 +31,7 @@
     },
     "plugins"   : [
         "local-plugins/proptomember",
+        "local-plugins/sourceproxy",
         "plugins/markdown"
     ],
     "templates": {

docs/build/local-plugins/sourceproxy.js

@@ -0,0 +1,38 @@
+/**
+* For use with custom `@sourcepath`, `@sourceline`, `@nosource` properties
+* (which are used in YUIDoc-to-JSDoc to supply source documentation)
+*/
+
+var path = require('path');
+
+exports.defineTags = function(dictionary) {
+
+    dictionary.defineTag('nosource', {
+        onTagged: function (doclet, tag) {
+            doclet.meta.nosource = true; 
+            //doclet.meta.path = '';
+            //doclet.meta.filename = '';
+        }
+    });
+
+    dictionary.defineTag('sourcefile', {
+        onTagged: function (doclet, tag) {
+            var filename = tag.value;
+            doclet.meta.path = path.dirname(filename);
+            doclet.meta.filename = path.basename(filename);
+        }
+    });
+
+    dictionary.defineTag('sourceline', {
+       onTagged: function (doclet, tag) {
+           var lineno = tag.value;
+           doclet.meta.lineno = lineno;
+       }
+    });
+
+}
+
+exports.handlers = {};
+exports.handlers.newDoclet = function (e) {
+
+};

package.json

@@ -40,6 +40,7 @@
     "grunt-contrib-uglify": "^0.4.0",
     "grunt-notify": "^0.3.0",
     "grunt-text-replace": "^0.3.11",
-    "load-grunt-config": "~0.7.2"
+    "load-grunt-config": "~0.7.2",
+    "yuidocjs": "^0.3.50"
   }
-}
+}

tasks/builddoc.js

@@ -0,0 +1,30 @@
+/**
+* A quick stub-task for running generating the JSDocs.
+* This should probably be migrated to use grunt-jsdoc@beta (for jsdoc 3.x) or similar.
+*/
+'use strict';
+
+module.exports = function (grunt) {
+
+  grunt.registerTask('builddoc', 'Builds the project documentation', function () {
+      
+    var done = this.async();
+
+    grunt.util.spawn({
+      cmd: 'jsdoc',
+      args: ['-c', 'conf.json', '../../README.md'],
+      opts: {
+          cwd: 'docs/build'
+      }
+    }, function (error, result, code) {
+        if (error) {
+            grunt.fail.warn("" + result);
+            done(false);
+        } else {
+            done();
+        }
+    });
+
+  });
+
+};

tasks/pixidoc.js

@@ -0,0 +1,58 @@
+/**
+* Generates the appropriate JSDoc from some (PIXI) YUIDoc.
+* This could be turned into a more general pacakge.
+*
+* Requires: yuidocjs
+*/
+'use strict';
+
+function generateYuiDoc (sourcePaths, grunt) {
+
+    var Y = require('yuidocjs');
+
+    var options = {
+        parseOnly: true,
+        quiet: true,
+        paths: sourcePaths
+    };
+
+    return (new Y.YUIDoc(options)).run();
+}
+
+module.exports = function (grunt) {
+
+  grunt.registerTask('pixidoc', 'Generates JSDoc from the PIXI YUIdocs', function () {
+
+      var sources = ['C:/code/ph/phaser/src/pixi'];
+      var output = 'docs/pixi-jsdoc.js';
+      
+      var yui2jsdoc = require('./yuidoc-to-jsdoc/converter');
+      var fs = require('fs');
+      var path = require('path');
+
+      // Right now yuidocsjs requires an absolute path so it emits an
+      // absolute path in the jsdoc (or the JSDoc will error on missing files)
+      sources = sources.map(function (source) {
+        return path.resolve(source);
+      });
+
+      var data = generateYuiDoc(sources);
+
+        if (!data) {
+            grunt.fail.warn("PIXI YUIDoc not generated - nothing to do")
+            return;
+        }
+
+        // Fake in namespace (current limitation)
+        var header =
+          "/**\n" +
+          "* @namespace PIXI\n" +
+          "*/";
+
+        var res = yui2jsdoc.convert(data);
+        var flat = res.join("\n");
+        fs.writeFileSync(output, header + "\n" + flat);
+
+  });
+
+};