Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

first commit

  • Loading branch information...
commit 740d6e960ef5128b6f53949a344cafa93bc0cbfb 0 parents
Tyler Kellen tkellen authored
3  .gitignore
... ... @@ -0,0 +1,3 @@
  1 +node_modules
  2 +npm-debug.log
  3 +tmp
3  AUTHORS
... ... @@ -0,0 +1,3 @@
  1 +George Pantazis (http://georgepantazis.com/)
  2 +Tyler Kellen (http://goingslowly.com/)
  3 +Chris Talkington (http://christalkington.com/)
22 LICENSE-MIT
... ... @@ -0,0 +1,22 @@
  1 +Copyright (c) 2012 "Cowboy" Ben Alman and contributors.
  2 +
  3 +Permission is hereby granted, free of charge, to any person
  4 +obtaining a copy of this software and associated documentation
  5 +files (the "Software"), to deal in the Software without
  6 +restriction, including without limitation the rights to use,
  7 +copy, modify, merge, publish, distribute, sublicense, and/or sell
  8 +copies of the Software, and to permit persons to whom the
  9 +Software is furnished to do so, subject to the following
  10 +conditions:
  11 +
  12 +The above copyright notice and this permission notice shall be
  13 +included in all copies or substantial portions of the Software.
  14 +
  15 +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16 +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  17 +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18 +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  19 +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  20 +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21 +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  22 +OTHER DEALINGS IN THE SOFTWARE.
53 README.md
Source Rendered
... ... @@ -0,0 +1,53 @@
  1 +# grunt-contrib-yuidoc
  2 +> Compile YUIDoc Documentation (part of the [grunt-contrib](/gruntjs/grunt-contrib) collection). Submitted by [George Pantazis](/gcpantazis).
  3 +
  4 +## Getting Started
  5 +Install this grunt plugin next to your project's [grunt.js gruntfile][getting_started] with: `npm install grunt-contrib-less`
  6 +
  7 +Then add this line to your project's `grunt.js` gruntfile:
  8 +
  9 +```javascript
  10 +grunt.loadNpmTasks('grunt-contrib-yuidoc');
  11 +```
  12 +
  13 +[grunt]: https://github.com/cowboy/grunt
  14 +[getting_started]: https://github.com/cowboy/grunt/blob/master/docs/getting_started.md
  15 +
  16 +### Overview
  17 +
  18 +Inside your `grunt.js` file add a section named `yuidoc`. [Visit the YUIDoc project home](http://yui.github.com/yuidoc/) for more information on YUIDocs and commenting syntax.
  19 +
  20 +#### Parameters
  21 +
  22 +##### options ```object```
  23 +
  24 +This controls how this task operates and should contain key:value pairs, see options below.
  25 +
  26 +#### Options
  27 +
  28 +Options correlate to [YUIDoc config objects](http://yui.github.com/yuidoc/args/index.html).
  29 +
  30 +##### paths (required) ```string|array```
  31 +
  32 +What directory should be scanned to generate doc data.
  33 +
  34 +##### outdir (required) ```string```
  35 +
  36 +Where to save the documentation.
  37 +
  38 +#### Config Example
  39 +
  40 +``` javascript
  41 +yuidoc: {
  42 + compile: {
  43 + "name": "Project Name",
  44 + "description": "Project Description",
  45 + "version": "1.0.2",
  46 + "url": "http://projecturl.com/",
  47 + options: {
  48 + paths: "path/to/source/code/",
  49 + outdir: "where/to/save/docs/"
  50 + }
  51 + }
  52 +}
  53 +```
89 grunt.js
... ... @@ -0,0 +1,89 @@
  1 +/*
  2 + * grunt-contrib-yuidoc
  3 + * http://gruntjs.com/
  4 + *
  5 + * Copyright (c) 2012 George Pantazis, contributors
  6 + * Licensed under the MIT license.
  7 + * https://github.com/gruntjs/grunt-contrib-yuidoc/blob/master/LICENSE-MIT
  8 + */
  9 +
  10 +module.exports = function(grunt) {
  11 + 'use strict';
  12 +
  13 + // Project configuration.
  14 + grunt.initConfig({
  15 + pkg: {
  16 + name: "grunt-contrib-yuidoc",
  17 + version: "0.1.0"
  18 + },
  19 +
  20 + lint: {
  21 + all: ['grunt.js', 'tasks/*.js', '<config:nodeunit.tasks>']
  22 + },
  23 + jshint: {
  24 + options: {
  25 + curly: true,
  26 + eqeqeq: true,
  27 + immed: true,
  28 + latedef: true,
  29 + newcap: true,
  30 + noarg: true,
  31 + sub: true,
  32 + undef: true,
  33 + boss: true,
  34 + eqnull: true,
  35 + node: true,
  36 + es5: true
  37 + }
  38 + },
  39 + // Before generating any new files, remove any previously-created files.
  40 + clean: {
  41 + test: ['tmp']
  42 + },
  43 + // Configuration to be run (and then tested).
  44 + yuidoc: {
  45 + compileA: {
  46 + "name": "Grunt Test",
  47 + "description": "Grunt Test Description",
  48 + "version": "1.2.1",
  49 + "url": "http://test.com/",
  50 + options: {
  51 + paths: "test/fixtures/app/",
  52 + outdir: "tmp/yuidoca/"
  53 + }
  54 + },
  55 + compileB: {
  56 + "name": "Grunt Test",
  57 + "description": "Grunt Test Description",
  58 + "version": "1.2.1",
  59 + "url": "http://test.com/",
  60 + options: {
  61 + paths: [
  62 + "test/fixtures/app/",
  63 + "test/fixtures/otherapp/"
  64 + ],
  65 + outdir: "tmp/yuidocb/"
  66 + }
  67 + }
  68 + },
  69 + // Unit tests.
  70 + nodeunit: {
  71 + tasks: ['test/*_test.js']
  72 + }
  73 + });
  74 +
  75 + // Actually load this plugin's task(s).
  76 + grunt.loadTasks('tasks');
  77 +
  78 + // The clean plugin helps in testing.
  79 + grunt.loadNpmTasks('grunt-contrib-clean');
  80 +
  81 + // Whenever the "test" task is run, first clean the "tmp" dir, then run this
  82 + // plugin's task(s), then test the result.
  83 + grunt.renameTask('test', 'nodeunit');
  84 + grunt.registerTask('test', 'clean yuidoc nodeunit');
  85 +
  86 + // By default, lint and run all tests.
  87 + grunt.registerTask('default', 'lint test');
  88 +
  89 +};
41 package.json
... ... @@ -0,0 +1,41 @@
  1 +{
  2 + "name": "grunt-contrib-yuidoc",
  3 + "description": "Compile YUIDoc Documentation.",
  4 + "version": "0.1.0",
  5 + "homepage": "https://github.com/gruntjs/grunt-contrib-yuidoc",
  6 + "author": {
  7 + "name": "George Pantazis",
  8 + "url": "http://georgepantazis.com/"
  9 + },
  10 + "repository": {
  11 + "type": "git",
  12 + "url": "git://github.com/gruntjs/grunt-contrib-yuidoc.git"
  13 + },
  14 + "bugs": {
  15 + "url": "https://github.com/gruntjs/grunt-contrib-yuidoc/issues"
  16 + },
  17 + "licenses": [
  18 + {
  19 + "type": "MIT",
  20 + "url": "https://github.com/gruntjs/grunt-contrib-yuidoc/blob/master/LICENSE-MIT"
  21 + }
  22 + ],
  23 + "main": "grunt.js",
  24 + "engines": {
  25 + "node": "*"
  26 + },
  27 + "scripts": {
  28 + "test": "grunt test"
  29 + },
  30 + "dependencies": {
  31 + "grunt-contrib-lib": "~0.1.0",
  32 + "yuidocjs": "~0.3.14"
  33 + },
  34 + "devDependencies": {
  35 + "grunt": "~0.3.15",
  36 + "grunt-contrib-clean": "~0.1.0"
  37 + },
  38 + "keywords": [
  39 + "gruntplugin"
  40 + ]
  41 +}
70 tasks/yuidoc.js
... ... @@ -0,0 +1,70 @@
  1 +/*
  2 + * grunt-contrib-yuidoc
  3 + * http://gruntjs.com/
  4 + *
  5 + * Copyright (c) 2012 George Pantazis, contributors
  6 + * Licensed under the MIT license.
  7 + * https://github.com/gruntjs/grunt-contrib-yuidoc/blob/master/LICENSE-MIT
  8 + */
  9 +
  10 +module.exports = function(grunt) {
  11 + "use strict";
  12 +
  13 + // TODO: ditch this when grunt v0.4 is released
  14 + grunt.util = grunt.util || grunt.utils;
  15 + var Y = require("yuidocjs");
  16 + var helpers = require("grunt-contrib-lib").init(grunt);
  17 + var kindOf = grunt.util.kindOf;
  18 +
  19 + grunt.registerMultiTask("yuidoc", "Create YUIDocs", function() {
  20 +
  21 + var done = this.async();
  22 + var starttime = (new Date()).getTime();
  23 + var json;
  24 +
  25 + var options = helpers.options(this, {
  26 + quiet: true
  27 + });
  28 +
  29 + // when invoking yuidocs via node, the project details
  30 + // are assigned under the options object using the key
  31 + // 'project'
  32 + options.project = this.data;
  33 +
  34 + grunt.verbose.writeflags(options, "Options");
  35 +
  36 + // Catch if required fields are not provided.
  37 + if ( !options.paths ) {
  38 + grunt.fail.warn("No path(s) provided for YUIDoc to scan.");
  39 + }
  40 + if ( !options.outdir ) {
  41 + grunt.fail.warn("You must specify a directory for YUIDoc output.");
  42 + }
  43 +
  44 + // ensure destination dir is available
  45 + grunt.file.mkdir(options.outdir);
  46 +
  47 + // Input path: array expected, but grunt conventions allows for either a string or an array.
  48 + if (kindOf(options.paths) === "string") {
  49 + options.paths = [ options.paths ];
  50 + }
  51 +
  52 + json = (new Y.YUIDoc(options)).run();
  53 +
  54 + options = Y.Project.mix(json, options);
  55 +
  56 + if (!options.parseOnly) {
  57 + var builder = new Y.DocBuilder(options, json);
  58 +
  59 + grunt.log.writeln("Start YUIDoc compile...");
  60 + grunt.log.writeln("Scanning: " + grunt.log.wordlist(options.paths));
  61 + grunt.log.writeln("Output: " + (options.outdir).cyan);
  62 +
  63 + builder.compile(function() {
  64 + var endtime = (new Date()).getTime();
  65 + grunt.log.writeln("YUIDoc compile completed in " + ((endtime - starttime) / 1000) + " seconds");
  66 + done();
  67 + });
  68 + }
  69 + });
  70 +};
27 test/fixtures/app/test.js
... ... @@ -0,0 +1,27 @@
  1 +/**
  2 + @module App
  3 + @class Global
  4 + @static
  5 + */
  6 +
  7 +var App = App || {};
  8 +
  9 +App.Global = (function() {
  10 +
  11 + var self = {
  12 +
  13 + /**
  14 + This is a sample method.
  15 + @method App.Global.init
  16 + @param foo {String} A sample parameter.
  17 + */
  18 + 'init': function(foo) {
  19 +
  20 + //
  21 +
  22 + }
  23 + };
  24 +
  25 + return self;
  26 +
  27 +})();
27 test/fixtures/otherapp/test.js
... ... @@ -0,0 +1,27 @@
  1 +/**
  2 + @module App
  3 + @class DeepClass
  4 + @static
  5 + */
  6 +
  7 +var App = App || {};
  8 +
  9 +App.DeepClass = (function() {
  10 +
  11 + var self = {
  12 +
  13 + /**
  14 + This is a sample method.
  15 + @method App.DeepClass.init
  16 + @param foo {String} A sample parameter.
  17 + */
  18 + 'init': function(foo) {
  19 +
  20 + //
  21 +
  22 + }
  23 + };
  24 +
  25 + return self;
  26 +
  27 +})();
33 test/yuidoc_test.js
... ... @@ -0,0 +1,33 @@
  1 +var grunt = require("grunt");
  2 +
  3 +// TODO: ditch this when grunt v0.4 is released
  4 +var fs = require("fs");
  5 +var path = require("path");
  6 +grunt.file.exists = grunt.file.exists || fs.existsSync || path.existsSync;
  7 +
  8 +exports['yuidoc'] = {
  9 + main: function(test) {
  10 + 'use strict';
  11 +
  12 + var expect, result;
  13 + test.expect(4);
  14 +
  15 + expect = true;
  16 + result = grunt.file.exists("tmp/yuidoca/data.json");
  17 + test.equal(result, expect, "If provided with a string path, Should generate JSON from source code");
  18 +
  19 + expect = true;
  20 + result = grunt.file.exists("tmp/yuidoca/index.html");
  21 + test.equal(result, expect, "If provided with a string path, Should create template files for viewing data.json");
  22 +
  23 + expect = true;
  24 + result = grunt.file.exists("tmp/yuidocb/data.json");
  25 + test.equal(result, expect, "If provided with an array of paths, should generate JSON from source code");
  26 +
  27 + expect = true;
  28 + result = grunt.file.exists("tmp/yuidocb/index.html");
  29 + test.equal(result, expect, "If provided with an array of paths, should create template files for viewing data.json");
  30 +
  31 + test.done();
  32 + }
  33 +};

0 comments on commit 740d6e9

Please sign in to comment.
Something went wrong with that request. Please try again.