Merge pull request #4 from ssafejava/master

Rework options parsing to use grunt's built-in options parsing and fix `outDir` location.

Gruntfile.js

@@ -10,6 +10,9 @@ module.exports = function (grunt) {
         },
 
         docker:{
+            options: {
+                exclude: '**/excluded.js'
+            },
             app:{
                 options: {
                     extras: ["fileSearch", "goToLine"],
@@ -55,5 +58,5 @@ module.exports = function (grunt) {
 
     // Default task.
     grunt.registerTask('default', 'jshint docker:app'.split( " " ));
-    grunt.registerTask('docker-test', 'docker:test nodeunit:test clean:test'.split( " " ));
+    grunt.registerTask('docker-test', 'clean:test docker:test nodeunit:test clean:test'.split( " " ));
 };

README.md

@@ -32,35 +32,61 @@ Then add some configuration for the plugin like so:
 grunt.initConfig({
   ...
   docker: {
+    options: {
+      // These options are applied to all tasks
+    },
     app: {
-      expand: true,
-      src: ['path/to/source/files/*.(coffee|js|...)'],
+      // Specify `src` and `dest` directly on the task object
+      src: ['path/to/source/files/*.{coffee,js}'],
       dest: 'where/you/want/your/generated/doc/files',
       options: {
-        onlyUpdated: false,
-        colourScheme: 'default',
-        ignoreHidden: false,
-        sidebarState: true,
-        exclude: false,
-        lineNums: false,
-        js: [],
-        css: [],
-        extras: []
+        // ...
       }
     }
   },
   ...
 });
 ```
 
+The default options are:
+
+```javascript
+options: {
+  inDir: '.',
+  outDir: 'doc',
+  onlyUpdated: false,
+  colourScheme: 'default',
+  ignoreHidden: false,
+  sidebarState: true,
+  exclude: false,
+  lineNums: false,
+  js: [],
+  css: [],
+  extras: []
+}
+```
+
+The options provided above are the defaults configured in [Docker](https://github.com/jbt/docker) and
+correspond to its CLI.
+
 Then just run `grunt docker` and enjoy!
 
-By default, Grunt Docker will use `src = "."` and `dest = "doc"` if they are not
-provided. `dest` will be given to Docker through the `options.outDir` option and
-`src` is used in the call to the doc generation as an `Array`.
+## Notes on output directory
+
+Docker itself doesn't quite follow Grunt convention, choosing to instead specify an `outDir`.
+If you need to output to more than one directory, define a new task; unfortunately, a single
+Docker object is allocated per-task and can only be used for a single output folder.
+
+Grunt-Docker will figure out the correct `outDir` property by reading Grunt's interpretation of
+`files.dest`. In most cases, this works fine. If you are having issues with relative paths, use 
+`options.outDir`, instead of `files.dest`.
+
+If your source files are above the current working directory (starting with `../), you *must* change
+`options.inDir`, or your docs will end up in the same folder as the source folders. For example, if
+my `src` property were `../../src/**/*.js`, I would set `options.inDir` to `'../../'.
 
-The options provided there are the defaults configured in [Docker](https://github.com/jbt/docker) and
-corresponds to the command line arguments that are possible to use.
+By default, Grunt-Docker will use `files.src = "."` and `options.outDir = "doc"` if they are not
+provided. `src` is used in the call to the doc generation as an `Array`.
 
 ## Contributing
 In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [grunt][grunt].

doc/tasks/docker.js.html

@@ -48,9 +48,20 @@ <h1>docker.js</h1>
         <td class="code highlight"><div class="highlight"><pre><span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="kd">function</span> <span class="p">(</span><span class="nx">grunt</span><span class="p">)</span> <span class="p">{</span>
     <span class="s2">&quot;use strict&quot;</span><span class="p">;</span>
     <span class="kd">var</span> <span class="nx">Docker</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;docker&#39;</span><span class="p">);</span>
+    <span class="kd">var</span> <span class="nx">path</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="s1">&#39;path&#39;</span><span class="p">);</span>
 
     <span class="nx">grunt</span><span class="p">.</span><span class="nx">registerMultiTask</span><span class="p">(</span><span class="s1">&#39;docker&#39;</span><span class="p">,</span> <span class="s1">&#39;Docker processor.&#39;</span><span class="p">,</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
-        <span class="kd">var</span> <span class="nx">options</span><span class="p">;</span>
+        <span class="kd">var</span> <span class="nx">options</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">options</span><span class="p">({</span>
+            <span class="nx">onlyUpdated</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
+            <span class="nx">colourScheme</span><span class="o">:</span> <span class="s1">&#39;default&#39;</span><span class="p">,</span>
+            <span class="nx">ignoreHidden</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
+            <span class="nx">sidebarState</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
+            <span class="nx">exclude</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
+            <span class="nx">lineNums</span><span class="o">:</span> <span class="kc">false</span><span class="p">,</span>
+            <span class="nx">js</span><span class="o">:</span> <span class="p">[],</span>
+            <span class="nx">css</span><span class="o">:</span> <span class="p">[],</span>
+            <span class="nx">extras</span><span class="o">:</span> <span class="p">[]</span>
+        <span class="p">});</span>
 
 
 </pre></div>
@@ -64,7 +75,6 @@ <h1>docker.js</h1>
 <p>Retrieve the configuration options according to the Docker documentation</p>
         </td>
         <td class="code highlight"><div class="highlight"><pre>
-        <span class="nx">options</span> <span class="o">=</span> <span class="nx">grunt</span><span class="p">.</span><span class="nx">config</span><span class="p">([</span><span class="s1">&#39;docker&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">target</span><span class="p">,</span> <span class="s1">&#39;options&#39;</span><span class="p">])</span> <span class="o">||</span> <span class="p">{};</span>
         <span class="nx">grunt</span><span class="p">.</span><span class="nx">verbose</span><span class="p">.</span><span class="nx">writeflags</span><span class="p">(</span><span class="nx">options</span><span class="p">,</span> <span class="s1">&#39;Options&#39;</span><span class="p">);</span>
 
 
@@ -84,9 +94,6 @@ <h1>docker.js</h1>
             <span class="k">for</span><span class="p">(</span> <span class="kd">var</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">f</span><span class="p">.</span><span class="nx">src</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span> <span class="p">){</span>
                 <span class="nx">src</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span> <span class="nx">f</span><span class="p">.</span><span class="nx">src</span><span class="p">[</span> <span class="nx">i</span> <span class="p">]</span> <span class="p">);</span>
             <span class="p">}</span>
-            <span class="nx">grunt</span><span class="p">.</span><span class="nx">verbose</span><span class="p">.</span><span class="nx">writeflags</span><span class="p">([</span><span class="nx">f</span><span class="p">.</span><span class="nx">dest</span><span class="p">],</span> <span class="s1">&#39;Destination&#39;</span><span class="p">);</span>
-        <span class="p">});</span>
-
 
 </pre></div>
         </td>
@@ -96,13 +103,15 @@ <h1>docker.js</h1>
 <div class="pilwrap">
   <a class="pilcrow" href="#section-4" id="section-4">&#182;</a>
 </div>
-<p>Getting the destination directory or file</p>
+<p>Attempt to automatically set the outDir if a 'dest' param is used.
+It's recommended to just use the 'outDir' option directly.</p>
         </td>
         <td class="code highlight"><div class="highlight"><pre>
-        <span class="kd">var</span> <span class="nx">_dest</span> <span class="o">=</span> <span class="nx">grunt</span><span class="p">.</span><span class="nx">config</span><span class="p">([</span><span class="s1">&#39;docker&#39;</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">target</span><span class="p">,</span> <span class="s1">&#39;dest&#39;</span><span class="p">]);</span>
-        <span class="k">if</span> <span class="p">(</span><span class="nx">_dest</span> <span class="o">!==</span> <span class="kc">undefined</span><span class="p">)</span> <span class="p">{</span>
-            <span class="nx">options</span><span class="p">.</span><span class="nx">outDir</span> <span class="o">=</span> <span class="nx">_dest</span><span class="p">;</span>   
-        <span class="p">}</span>
+            <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nx">options</span><span class="p">.</span><span class="nx">outDir</span> <span class="o">&amp;&amp;</span> <span class="nx">f</span><span class="p">.</span><span class="nx">dest</span><span class="p">){</span>
+                <span class="nx">options</span><span class="p">.</span><span class="nx">outDir</span> <span class="o">=</span> <span class="nx">f</span><span class="p">.</span><span class="nx">dest</span><span class="p">.</span><span class="nx">replace</span><span class="p">(</span><span class="nx">f</span><span class="p">.</span><span class="nx">src</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">);</span>
+            <span class="p">}</span>
+            <span class="nx">grunt</span><span class="p">.</span><span class="nx">verbose</span><span class="p">.</span><span class="nx">writeflags</span><span class="p">([</span><span class="nx">f</span><span class="p">.</span><span class="nx">dest</span><span class="p">],</span> <span class="s1">&#39;Destination&#39;</span><span class="p">);</span>
+        <span class="p">});</span>
 
         <span class="kd">var</span> <span class="nx">done</span> <span class="o">=</span> <span class="k">this</span><span class="p">.</span><span class="nx">async</span><span class="p">();</span>
 
@@ -150,12 +159,7 @@ <h1>docker.js</h1>
 <p>Generate the documentation</p>
         </td>
         <td class="code highlight"><div class="highlight"><pre>
-        <span class="k">if</span> <span class="p">(</span><span class="nx">src</span> <span class="o">===</span> <span class="kc">undefined</span><span class="p">)</span> <span class="p">{</span>
-            <span class="nx">docker</span><span class="p">.</span><span class="nx">doc</span><span class="p">();</span>
-        <span class="p">}</span>
-        <span class="k">else</span> <span class="p">{</span>
-            <span class="nx">docker</span><span class="p">.</span><span class="nx">doc</span><span class="p">(</span><span class="nx">src</span><span class="p">);</span>
-        <span class="p">}</span>
+        <span class="nx">docker</span><span class="p">.</span><span class="nx">doc</span><span class="p">(</span><span class="nx">src</span><span class="p">);</span>
     <span class="p">});</span>
 <span class="p">};</span>
 </pre></div>

tasks/docker.js

@@ -6,29 +6,38 @@
 module.exports = function (grunt) {
     "use strict";
     var Docker = require('docker');
+    var path = require('path');
 
     grunt.registerMultiTask('docker', 'Docker processor.', function () {
-        var options;
+        var options = this.options({
+            onlyUpdated: false,
+            colourScheme: 'default',
+            ignoreHidden: false,
+            sidebarState: true,
+            exclude: false,
+            lineNums: false,
+            js: [],
+            css: [],
+            extras: []
+        });
 
         // Retrieve the configuration options according to the Docker documentation
-        options = grunt.config(['docker', this.target, 'options']) || {};
         grunt.verbose.writeflags(options, 'Options');
 
         // Getting the source directory or file
         var src = [];
         this.files.forEach(function(f) {
             for( var i = 0; i < f.src.length; i++ ){
-                src.push( f.src[ i ] );
+                src.push( f.src[ i ].replace(options.inDir, '') );
+            }
+            // Attempt to automatically set the outDir if a 'dest' param is used.
+            // It's recommended to just use the 'outDir' option directly.
+            if (!options.outDir && f.dest){
+                options.outDir = f.dest.replace(f.src, '');
             }
             grunt.verbose.writeflags([f.dest], 'Destination');
         });
 
-        // Getting the destination directory or file
-        var _dest = grunt.config(['docker', this.target, 'dest']);
-        if (_dest !== undefined) {
-            options.outDir = _dest;   
-        }
-
         var done = this.async();
 
         // Hack docker to call the done callback when the documentation generation is finished
@@ -42,11 +51,6 @@ module.exports = function (grunt) {
         var docker = new Docker(options);
 
         // Generate the documentation
-        if (src === undefined) {
-            docker.doc();
-        }
-        else {
-            docker.doc(src);
-        }
+        docker.doc(src);
     });
 };

test/docker_test.js

@@ -8,10 +8,12 @@ exports.docker = {
      var css = grunt.file.read("test/docs/doc-style.css");
      var fileList = grunt.file.read("test/docs/doc-filelist.js");
      var fileScript = grunt.file.read("test/docs/doc-script.js");
+     var excludedFileExists = grunt.file.exists("test/docs/test/fixtures/docker/excluded.js.html");
 
-     test.expect(4);
+     test.expect(5);
      test.equal(css.length, 11040, "Should create CSS.");
      test.equal(html.length, 1989, "Should create HTML.");
+     test.equal(excludedFileExists, false, "Should exclude excluded file (set in general options)");
      test.equal(fileList.length, 93, "Should create doc-filelist.js");
      test.equal(fileScript.length, 7461, "Should create doc-script.js");
      test.done();

test/fixtures/docker/excluded.js

@@ -0,0 +1,7 @@
+/**
+ * Amazing function to show a specific alert
+ */
+function amazing() {
+    // Open an alert with the Amazing !!! text
+    window.alert("Amazing !!!");
+}