diff --git a/.jshintrc b/.jshintrc new file mode 100644 index 0000000..a685fff --- /dev/null +++ b/.jshintrc @@ -0,0 +1,13 @@ +{ + "curly": true, + "eqeqeq": true, + "immed": true, + "newcap": true, + "noarg": true, + "sub": true, + "undef": true, + "boss": true, + "eqnull": true, + "node": true, + "es5": true +} diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..2ccbe46 --- /dev/null +++ b/.npmignore @@ -0,0 +1 @@ +/node_modules/ diff --git a/Gruntfile.js b/Gruntfile.js new file mode 100644 index 0000000..38db98c --- /dev/null +++ b/Gruntfile.js @@ -0,0 +1,48 @@ +'use strict'; + +module.exports = function(grunt) { + + // Project configuration. + grunt.initConfig({ + nodeunit: { + files: ['test/**/*_test.js'], + }, + jshint: { + options: { + jshintrc: '.jshintrc' + }, + gruntfile: { + src: 'Gruntfile.js' + }, + lib: { + src: ['lib/**/*.js', 'bin/*'] + }, + test: { + src: ['test/**/*.js'] + }, + }, + watch: { + gruntfile: { + files: '<%= jshint.gruntfile.src %>', + tasks: ['jshint:gruntfile'] + }, + lib: { + files: '<%= jshint.lib.src %>', + tasks: ['jshint:lib', 'nodeunit'] + }, + test: { + files: '<%= jshint.test.src %>', + tasks: ['jshint:test', 'nodeunit'] + }, + }, + }); + + // These plugins provide necessary tasks. + grunt.loadNpmTasks('grunt-contrib-nodeunit'); + grunt.loadNpmTasks('grunt-contrib-jshint'); + grunt.loadNpmTasks('grunt-contrib-watch'); + + // Default task. + grunt.registerTask('default', ['jshint', 'nodeunit']); + +}; diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..e98edaa --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,22 @@ +Copyright (c) 2012 Matt McManus + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ea9bb4 --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# grunt-doxmate + +Doxmate grunt plugin to automatically generate documentation for you project. Currently generates HTML output using [doxmate](https://github.com/JackjsonTian/doxmate) + +## Getting Started +This plugin requires Grunt `~0.4.0` + +If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command: + +```shell +npm install grunt-doxmate --save-dev +``` + +Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript: + +```js +grunt.loadNpmTasks('grunt-doxmate'); +``` + +## Documentation +Inside of your grunt file, add: +```javascript +dox: { + options: { + title: "My Library's awesome documentation" + }, + files: { + src: ['js/lib/'], + dest: 'docs' + } +}, +``` + +This will run all of your files in `lib` through dox and dox-foundation and put the output in `docs`. + +Since the `grunt-dox` task is a multi task, you can create several tasks for dox: + +```js +dox: { + libdocs :{ + files: { + src: ['js/lib/'], + dest: 'docs' + } + }, + sourcedocs :{ + files: { + src: ['js/src/'], + dest: 'docs' + } + } +}, +``` + +To ignore certain directories, or to override the default ignore list, simpy add ignore and an array of paths. Note that this is the same as passing the `--ignore` parameter as described on the [dox-foundation docs](https://github.com/punkave/dox-foundation/blob/master/README.md): + +``` +--ignore Comma seperated list of directories to ignore. Overrides default of test, public, static, views, templates +``` + +Usage: + +```js +dox: { + options: { + title: 'Ignore Nothing for my awesome documentation' + }, + files: { + ignore: ['test'], + src: ['js/src/'], + dest: 'docs' + } +} +``` + +**Note:** This will completely delete and recreate the docs folder + +## 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]. + +## Release History +* **0.3.2** *2013-03-20*: +** Grunt v0.4 support +** Ability to pass options.title to dox-foundation +* **0.3.0**: Now relies solely on folder parsing done by dox-foundation v0.4 +* **0.2.0**: Pass multiple files at once. Use dox-foundation for html output +* **0.1.0**: Initial release + +## License +Copyright (c) 2012 P'unk Ave +Licensed under the MIT license. diff --git a/bin/grunt-dox b/bin/grunt-dox new file mode 100644 index 0000000..cc60efe --- /dev/null +++ b/bin/grunt-dox @@ -0,0 +1,2 @@ +#!/usr/bin/env node +require('grunt').npmTasks('grunt-dox').cli(); diff --git a/package.json b/package.json new file mode 100644 index 0000000..ba1f7aa --- /dev/null +++ b/package.json @@ -0,0 +1,52 @@ +{ + "name": "grunt-doxmate", + "description": "Doxmate grunt plugin", + "version": "0.1.0", + "homepage": "https://github.com/luozhihua/grunt-doxmate", + "author": "Colin Luo ", + "repository": { + "type": "git", + "url": "git://github.com/luozhihua/grunt-doxmate.git" + }, + "bugs": { + "url": "https://github.com/luozhihua/grunt-doxmate/issues" + }, + "licenses": [ + { + "type": "MIT", + "url": "https://github.com/luozhihua/grunt-doxmate/blob/master/LICENSE-MIT" + } + ], + "main": "grunt.js", + "bin": { + "grunt-doxmate": "bin/grunt-doxmate" + }, + "engines": { + "node": "*" + }, + "scripts": { + "test": "grunt nodeunit" + }, + "dependencies": { + "dox": "*", + "doxmate": "~0.5.0", + "rimraf": "2.x" + }, + "devDependencies": { + "grunt": "~0.4.0", + "grunt-contrib-jshint": "~0.1.1", + "grunt-contrib-watch": "~0.2.0", + "grunt-contrib-nodeunit": "~0.1.2" + }, + "keywords": [ + "gruntplugin" + ], + "dist": { + "shasum": "2876a30e32c3716b8da12caa560959405f5dd76c" + }, + "_from": "grunt-doxmate", + "directories": { + "test": "test" + }, + "license": "BSD" +} diff --git a/tasks/doxmate.js b/tasks/doxmate.js new file mode 100644 index 0000000..369a96a --- /dev/null +++ b/tasks/doxmate.js @@ -0,0 +1,86 @@ +/* + * grunt-doxmate + * https://github.com/luozhihua/grunt-doxmate + * + * Copyright (c) 2014 Colin Luo + * Licensed under the MIT license. + */ + +var exec = require('child_process').exec, + fs = require('fs'), + path = require('path'), + rimraf = require('rimraf'); + + +module.exports = function(grunt) { + + grunt.registerMultiTask('doxmate', 'Generate dox output ', function() { + + var dir = this.filesSrc, + dest = this.data.dest, + done = this.async(), + doxPath = path.resolve(__dirname, '../'), + opts = this.options(), + args = [], + cmd; + + if (this.data.output) { + args.push('-o'); + args.push(this.data.output); + } + + if (this.data.theme) { + args.push('-s'); + args.push(this.data.theme); + } + + if (this.data.dir) { + args.push('-d'); + args.push(this.data.dir); + } + + cmd = 'doxmate build ' + args.join(' '); + exec(cmd, {maxBuffer: 5000*1024}, function(error, stout, sterr) { + if (error) { grunt.log.error("ERROR: "+ error); } + if (!error) { + grunt.log.ok('Directory "' + dir + '" doxxed.'); + done(); + } + }); + // Absolute path to the formatter + //var formatter = [doxPath, 'node_modules', '.bin', 'doxmate'].join(path.sep); + +/* + // Cleanup any existing docs + rimraf.sync(dest); + + _args.push('--source'); + _args.push(dir); + _args.push('--o'); + _args.push(dest); + + // Set options to arguments + if(_opts.title){ + _args.push('--title'); + _args.push('"' + _opts.title + '"'); + } + + // Pass through ignore params if set + if (this.data.ignore) { + _args.push('--ignore'); + this.data.ignore.forEach(function(ignorePath) { + _args.push(doxPath + ignorePath); + }); + + } + + exec('doxmate build ' + _args.join(" "), {maxBuffer: 5000*1024}, function(error, stout, sterr){ + if (error) { grunt.log.error("ERROR: "+ error); } + if (!error) { + grunt.log.ok('Directory "' + dir + '" doxxed.'); + done(); + } + }); +*/ + }); +}; diff --git a/test/dox_test.js b/test/dox_test.js new file mode 100644 index 0000000..594edfa --- /dev/null +++ b/test/dox_test.js @@ -0,0 +1,37 @@ +'use strict'; + +var grunt = require('grunt'); + +/* + ======== A Handy Little Nodeunit Reference ======== + https://github.com/caolan/nodeunit + + Test methods: + test.expect(numAssertions) + test.done() + Test assertions: + test.ok(value, [message]) + test.equal(actual, expected, [message]) + test.notEqual(actual, expected, [message]) + test.deepEqual(actual, expected, [message]) + test.notDeepEqual(actual, expected, [message]) + test.strictEqual(actual, expected, [message]) + test.notStrictEqual(actual, expected, [message]) + test.throws(block, [error], [message]) + test.doesNotThrow(block, [error], [message]) + test.ifError(value) +*/ + +exports['dox'] = { + setUp: function(done) { + // setup here + done(); + }, + 'helper': function(test) { + test.expect(1); + // tests here + test.ok(true); + // test.equal(grunt.helper('dox'), 'dox!!!', 'should return the correct value.'); + test.done(); + } +};