Rename JSDuck config to standard 'jsduck'

* Move configuration to /jsduck.json per standard. This way
  it can be run as plain '$ jsduck' without needing a maintenance
  script or custom Jenkins job. Similar to JSHint, JSCS, Grunt,
  and Gem etc.

* Move --processes=0 from maintenace script into config file.
  This should've been in the config file all along and serves as
  workaround for https://github.com/senchalabs/jsduck/issues/525.

* Use grunt-contrib-copy instead of a symlink for resources.
  For local development a symlink works fine, but for publishing
  from Jenkins to doc.wikimedia.org the /docs/js/ directory needs
  to be standalone. This was previously done with a manual post-build
  step that added an additional rsync, but this logic should be
  in the repository so that the doc entry point can be simplified
  and standardised to 'npm run-script doc' for all projects.

Change-Id: Iaaaac50ee78dd9ff8f24f1ef3a3685ad51cf33b2

diff --git a/Gruntfile.js b/Gruntfile.js
index e432279..a292d0b 100644 (file)
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -1,5 +1,6 @@
 /*jshint node:true */
 module.exports = function ( grunt ) {
+       grunt.loadNpmTasks( 'grunt-contrib-copy' );
        grunt.loadNpmTasks( 'grunt-contrib-jshint' );
        grunt.loadNpmTasks( 'grunt-contrib-watch' );
        grunt.loadNpmTasks( 'grunt-banana-checker' );
@@ -83,6 +84,16 @@ module.exports = function ( grunt ) {
                        more: {
                                browsers: [ 'Chrome', 'Firefox' ]
                        }
+               },
+               copy: {
+                       jsduck: {
+                               src: 'resources/**/*',
+                               dest: 'docs/js/modules',
+                               expand: true,
+                               rename: function ( dest, src ) {
+                                       return require( 'path' ).join( dest, src.replace( 'resources/', '' ) );
+                               }
+                       }
                }
        } );
 

diff --git a/jsduck.json b/jsduck.json
new file mode 100644 (file)
index 0000000..afd2bd8
--- /dev/null
+++ b/jsduck.json
@@ -0,0 +1,41 @@
+{
+       "--title": "MediaWiki core - Documentation",
+       "--categories": "maintenance/jsduck/categories.json",
+       "--eg-iframe": "maintenance/jsduck/eg-iframe.html",
+       "--tags": "maintenance/jsduck/CustomTags.rb",
+       "--warnings": ["-nodoc(class,public)"],
+       "--builtin-classes": true,
+       "--processes": "0",
+       "--warnings-exit-nonzero": true,
+       "--external": "HTMLElement,HTMLDocument,Window,File,MouseEvent,KeyboardEvent",
+       "--output": "docs/js",
+       "--": [
+               "maintenance/jsduck/external.js",
+               "resources/src/mediawiki",
+               "resources/src/mediawiki.action",
+               "resources/src/mediawiki.api",
+               "resources/src/mediawiki.language",
+               "resources/src/mediawiki.page",
+               "resources/src/mediawiki.special",
+               "resources/src/mediawiki.toolbar",
+               "resources/src/jquery/jquery.accessKeyLabel.js",
+               "resources/src/jquery/jquery.arrowSteps.js",
+               "resources/src/jquery/jquery.autoEllipsis.js",
+               "resources/src/jquery/jquery.badge.js",
+               "resources/src/jquery/jquery.byteLength.js",
+               "resources/src/jquery/jquery.byteLimit.js",
+               "resources/src/jquery/jquery.checkboxShiftClick.js",
+               "resources/src/jquery/jquery.client.js",
+               "resources/src/jquery/jquery.colorUtil.js",
+               "resources/src/jquery/jquery.confirmable.js",
+               "resources/src/jquery/jquery.footHovzer.js",
+               "resources/src/jquery/jquery.getAttrs.js",
+               "resources/src/jquery/jquery.hidpi.js",
+               "resources/src/jquery/jquery.localize.js",
+               "resources/src/jquery/jquery.makeCollapsible.js",
+               "resources/src/jquery/jquery.spinner.js",
+               "resources/src/jquery/jquery.tabIndex.js",
+               "resources/lib/oojs",
+               "resources/lib/oojs-ui"
+       ]
+}

diff --git a/maintenance/jsduck/config.json b/maintenance/jsduck/config.json
deleted file mode 100644 (file)
index c2499ff..0000000
--- a/maintenance/jsduck/config.json
+++ /dev/null
@@ -1,41 +0,0 @@
-{
-       "--title": "MediaWiki core - Documentation",
-       "--categories": "./categories.json",
-       "--eg-iframe": "./eg-iframe.html",
-       "--tags": "./CustomTags.rb",
-       "--warnings": ["-nodoc(class,public)"],
-       "--builtin-classes": true,
-       "--warnings-exit-nonzero": true,
-       "--external": "HTMLElement,HTMLDocument,Window,File,MouseEvent,KeyboardEvent",
-       "--footer": "Documentation for MediaWiki core. Generated on {DATE} by {JSDUCK} {VERSION}.",
-       "--output": "../../docs/js",
-       "--": [
-               "./external.js",
-               "../../resources/src/mediawiki",
-               "../../resources/src/mediawiki.action",
-               "../../resources/src/mediawiki.api",
-               "../../resources/src/mediawiki.language",
-               "../../resources/src/mediawiki.page",
-               "../../resources/src/mediawiki.special",
-               "../../resources/src/mediawiki.toolbar",
-               "../../resources/src/jquery/jquery.accessKeyLabel.js",
-               "../../resources/src/jquery/jquery.arrowSteps.js",
-               "../../resources/src/jquery/jquery.autoEllipsis.js",
-               "../../resources/src/jquery/jquery.badge.js",
-               "../../resources/src/jquery/jquery.byteLength.js",
-               "../../resources/src/jquery/jquery.byteLimit.js",
-               "../../resources/src/jquery/jquery.checkboxShiftClick.js",
-               "../../resources/src/jquery/jquery.client.js",
-               "../../resources/src/jquery/jquery.colorUtil.js",
-               "../../resources/src/jquery/jquery.confirmable.js",
-               "../../resources/src/jquery/jquery.footHovzer.js",
-               "../../resources/src/jquery/jquery.getAttrs.js",
-               "../../resources/src/jquery/jquery.hidpi.js",
-               "../../resources/src/jquery/jquery.localize.js",
-               "../../resources/src/jquery/jquery.makeCollapsible.js",
-               "../../resources/src/jquery/jquery.spinner.js",
-               "../../resources/src/jquery/jquery.tabIndex.js",
-               "../../resources/lib/oojs",
-               "../../resources/lib/oojs-ui"
-       ]
-}

diff --git a/maintenance/mwjsduck-gen b/maintenance/mwjsduck-gen
index 5247637..6b7c77b 100755 (executable)
--- a/maintenance/mwjsduck-gen
+++ b/maintenance/mwjsduck-gen
@@ -1,25 +1,4 @@
 #!/usr/bin/env bash
 set -e
-
-JSDUCK_MWVERSION=master
-if [[ "$1" == "--version" && "$2" != "" ]]
-then
-       JSDUCK_MWVERSION="$2"
-elif [[ "$*" != "" ]]
-then
-       FILENAME=$(basename $0)
-       echo "Usage: $FILENAME [--version <mediawiki version>]"
-       echo
-       exit 1
-fi
-
-MWCORE_DIR=$(cd $(dirname $0)/..; pwd)
-
-jsduck \
---config=$MWCORE_DIR/maintenance/jsduck/config.json \
---footer="Documentation for branch ($JSDUCK_MWVERSION) on {DATE} by {JSDUCK} {VERSION}." \
---processes 0
-
-echo 'JSDuck execution finished.'
-
-ln -s ../../resources $MWCORE_DIR/docs/js/modules
+cd $(dirname $0)/..
+jsduck

diff --git a/package.json b/package.json
index 4ef12ba..076582b 100644 (file)
--- a/package.json
+++ b/package.json
@@ -2,11 +2,14 @@
   "name": "mediawiki",
   "version": "0.0.0",
   "scripts": {
-    "test": "grunt test"
+    "test": "grunt test",
+    "doc": "jsduck",
+    "postdoc": "grunt copy:jsduck"
   },
   "devDependencies": {
     "grunt": "0.4.5",
     "grunt-banana-checker": "0.2.0",
+    "grunt-contrib-copy": "0.8.0",
     "grunt-contrib-jshint": "0.11.0",
     "grunt-contrib-watch": "0.6.1",
     "grunt-jscs": "1.5.0",