From ef01195079f4d83aeea4f521beba85c7f2e313ca Mon Sep 17 00:00:00 2001 From: Marcin Wosinek Date: Sun, 19 Jan 2014 01:43:35 +0000 Subject: [PATCH] feat(gen) add grunt-ngdoc Add jsdoc to generated text and add grunt-ngdocs generated documentation to /docs. Add grunt-ngdocs to package.json & Gruntfile.js. Basic support in js & coffee templates. Watch for changes in files & autoreload docs after regeneration. Init work at #550 --- templates/coffeescript/app.coffee | 10 ++++++- templates/coffeescript/controller.coffee | 7 +++++ templates/coffeescript/decorator.coffee | 7 +++++ templates/coffeescript/directive.coffee | 7 +++++ templates/coffeescript/filter.coffee | 8 ++++++ .../coffeescript/service/constant.coffee | 7 +++++ templates/coffeescript/service/factory.coffee | 7 +++++ .../coffeescript/service/provider.coffee | 7 +++++ templates/coffeescript/service/service.coffee | 7 +++++ templates/coffeescript/service/value.coffee | 7 +++++ templates/common/Gruntfile.js | 28 ++++++++++++++++++- templates/common/_package.json | 3 +- templates/javascript/app.js | 8 ++++++ templates/javascript/controller.js | 7 +++++ templates/javascript/decorator.js | 7 +++++ templates/javascript/directive.js | 7 +++++ templates/javascript/filter.js | 8 ++++++ templates/javascript/service/constant.js | 7 +++++ templates/javascript/service/factory.js | 7 +++++ templates/javascript/service/provider.js | 7 +++++ templates/javascript/service/service.js | 7 +++++ templates/javascript/service/value.js | 7 +++++ 22 files changed, 174 insertions(+), 3 deletions(-) diff --git a/templates/coffeescript/app.coffee b/templates/coffeescript/app.coffee index 3106b4d51..74618cff7 100644 --- a/templates/coffeescript/app.coffee +++ b/templates/coffeescript/app.coffee @@ -1,5 +1,13 @@ 'use strict' +###* + * @ngdoc overview + * @name <%= scriptAppName %> + * @description + * # <%= scriptAppName %> + * + * Main module of the application. +### angular.module('<%= scriptAppName %>', [<%= angularModules %>])<% if (ngRoute) { %> .config ($routeProvider) -> $routeProvider @@ -8,4 +16,4 @@ angular.module('<%= scriptAppName %>', [<%= angularModules %>])<% if (ngRoute) { controller: 'MainCtrl' .otherwise redirectTo: '/' -<% } %> \ No newline at end of file +<% } %> diff --git a/templates/coffeescript/controller.coffee b/templates/coffeescript/controller.coffee index cf02fd99c..b36c4f916 100644 --- a/templates/coffeescript/controller.coffee +++ b/templates/coffeescript/controller.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc function + * @name <%= scriptAppName %>.controller:<%= classedName %>Ctrl + * @description + * # <%= classedName %>Ctrl + * Controller of the <%= scriptAppName %> +### angular.module('<%= scriptAppName %>') .controller '<%= classedName %>Ctrl', ($scope) -> $scope.awesomeThings = [ diff --git a/templates/coffeescript/decorator.coffee b/templates/coffeescript/decorator.coffee index 956e53b6d..1c5729362 100644 --- a/templates/coffeescript/decorator.coffee +++ b/templates/coffeescript/decorator.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc function + * @name <%= scriptAppName %>.decorator:<%= classedName %> + * @description + * # <%= classedName %>Ctrl + * Decorator of the <%= scriptAppName %> +### angular.module("<%= scriptAppName %>").config ($provide) -> $provide.decorator "<%= cameledName %>", ($delegate) -> # decorate the $delegate diff --git a/templates/coffeescript/directive.coffee b/templates/coffeescript/directive.coffee index 9f41a6589..3f5cdf6c8 100644 --- a/templates/coffeescript/directive.coffee +++ b/templates/coffeescript/directive.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc directive + * @name <%= scriptAppName %>.directive:<%= cameledName %> + * @description + * # <%= cameledName %> + * Directive to replace content with custom text. +### angular.module('<%= scriptAppName %>') .directive('<%= cameledName %>', -> template: '
' diff --git a/templates/coffeescript/filter.coffee b/templates/coffeescript/filter.coffee index b958ef83a..707512de2 100644 --- a/templates/coffeescript/filter.coffee +++ b/templates/coffeescript/filter.coffee @@ -1,5 +1,13 @@ 'use strict' +###* + * @ngdoc filter + * @name <%= scriptAppName %>.filter:<%= cameledName %> + * @function + * @description + * # <%= cameledName %> + * Filter to change your value. +### angular.module('<%= scriptAppName %>') .filter '<%= cameledName %>', -> (input) -> diff --git a/templates/coffeescript/service/constant.coffee b/templates/coffeescript/service/constant.coffee index 49c0af7e2..70f7221f7 100644 --- a/templates/coffeescript/service/constant.coffee +++ b/templates/coffeescript/service/constant.coffee @@ -1,4 +1,11 @@ 'use strict' +###* + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Constat in the <%= scriptAppName %>. +### angular.module('<%= scriptAppName %>') .constant '<%= cameledName %>', 42 diff --git a/templates/coffeescript/service/factory.coffee b/templates/coffeescript/service/factory.coffee index 53d95e3a0..6311d6604 100644 --- a/templates/coffeescript/service/factory.coffee +++ b/templates/coffeescript/service/factory.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Factory in the <%= scriptAppName %>. +### angular.module('<%= scriptAppName %>') .factory '<%= cameledName %>', -> # Service logic diff --git a/templates/coffeescript/service/provider.coffee b/templates/coffeescript/service/provider.coffee index 9a8611bb2..8a2c7bda9 100644 --- a/templates/coffeescript/service/provider.coffee +++ b/templates/coffeescript/service/provider.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Provider in the <%= scriptAppName %>. +### angular.module('<%= scriptAppName %>') .provider '<%= cameledName %>', [-> diff --git a/templates/coffeescript/service/service.coffee b/templates/coffeescript/service/service.coffee index 0b04291f2..6817539c6 100644 --- a/templates/coffeescript/service/service.coffee +++ b/templates/coffeescript/service/service.coffee @@ -1,5 +1,12 @@ 'use strict' +###* + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Service in the <%= scriptAppName %>. +### angular.module('<%= scriptAppName %>') .service '<%= classedName %>', -> # AngularJS will instantiate a singleton by calling "new" on this function diff --git a/templates/coffeescript/service/value.coffee b/templates/coffeescript/service/value.coffee index 5e6b5427c..756d1aba3 100644 --- a/templates/coffeescript/service/value.coffee +++ b/templates/coffeescript/service/value.coffee @@ -1,4 +1,11 @@ 'use strict' +###* + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Value in the <%= scriptAppName %>. +### angular.module('<%= scriptAppName %>') .value '<%= cameledName %>', 42 diff --git a/templates/common/Gruntfile.js b/templates/common/Gruntfile.js index c36416ae2..d71393cec 100644 --- a/templates/common/Gruntfile.js +++ b/templates/common/Gruntfile.js @@ -34,10 +34,17 @@ module.exports = function (grunt) { coffeeTest: { files: ['test/spec/{,*/}*.{coffee,litcoffee,coffee.md}'], tasks: ['newer:coffee:test', 'karma'] + }, + js: { + files: ['.tmp/scripts/{,*/}*.js'], + tasks: ['ngdocs'], + options: { + livereload: true + } },<% } else { %> js: { files: ['<%%= yeoman.app %>/scripts/{,*/}*.js'], - tasks: ['newer:jshint:all'], + tasks: ['ngdocs', 'newer:jshint:all'], options: { livereload: true } @@ -352,6 +359,16 @@ module.exports = function (grunt) { cwd: '<%%= yeoman.app %>/styles', dest: '.tmp/styles/', src: '{,*/}*.css' + }, + ngdocs: { + expand: true, + cwd: '<%%= yeoman.app %>/docs', + dest: '.tmp/docs/', + src: [ + '*.{ico,png,txt}', + '.htaccess', + '*.html', + ] } }, @@ -408,6 +425,13 @@ module.exports = function (grunt) { configFile: 'karma.conf.js', singleRun: true } + }, + ngdocs: { + options: { + dest: '.tmp/docs', + html5Mode: false + }, + api: ['<% if (coffee) { %>.tmp<% } else { %><%%= yeoman.app %><% } %>/scripts/{,*/}*.js'], } }); @@ -422,6 +446,7 @@ module.exports = function (grunt) { 'bower-install', 'concurrent:server', 'autoprefixer', + 'ngdocs', 'connect:livereload', 'watch' ]); @@ -448,6 +473,7 @@ module.exports = function (grunt) { 'autoprefixer', 'concat', 'ngmin', + 'ngdocs', 'copy:dist', 'cdnify', 'cssmin', diff --git a/templates/common/_package.json b/templates/common/_package.json index dcff45787..c4bfcbf42 100644 --- a/templates/common/_package.json +++ b/templates/common/_package.json @@ -27,7 +27,8 @@ "grunt-usemin": "~2.0.0", "jshint-stylish": "~0.1.3", "load-grunt-tasks": "~0.2.0", - "time-grunt": "~0.2.1" + "time-grunt": "~0.2.1", + "grunt-ngdocs": "~0.1.7" }, "engines": { "node": ">=0.10.0" diff --git a/templates/javascript/app.js b/templates/javascript/app.js index 58f75e3dc..81aa3f1d3 100644 --- a/templates/javascript/app.js +++ b/templates/javascript/app.js @@ -1,5 +1,13 @@ 'use strict'; +/** + * @ngdoc overview + * @name <%= scriptAppName %> + * @description + * # <%= scriptAppName %> + * + * Main module of the application. + */ angular.module('<%= scriptAppName %>', [<%= angularModules %>])<% if (ngRoute) { %> .config(function ($routeProvider) { $routeProvider diff --git a/templates/javascript/controller.js b/templates/javascript/controller.js index 216a5ea20..e51d4fc63 100644 --- a/templates/javascript/controller.js +++ b/templates/javascript/controller.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc function + * @name <%= scriptAppName %>.controller:<%= classedName %>Ctrl + * @description + * # <%= classedName %>Ctrl + * Controller of the <%= scriptAppName %> + */ angular.module('<%= scriptAppName %>') .controller('<%= classedName %>Ctrl', function ($scope) { $scope.awesomeThings = [ diff --git a/templates/javascript/decorator.js b/templates/javascript/decorator.js index 78fb3893f..35b943e7d 100644 --- a/templates/javascript/decorator.js +++ b/templates/javascript/decorator.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc function + * @name <%= scriptAppName %>.decorator:<%= classedName %> + * @description + * # <%= classedName %>Ctrl + * Decorator of the <%= scriptAppName %> + */ angular.module('<%= scriptAppName %>') .config(function ($provide) { $provide.decorator('<%= cameledName %>', function ($delegate) { diff --git a/templates/javascript/directive.js b/templates/javascript/directive.js index 57b0e1f3d..b02b14ea1 100644 --- a/templates/javascript/directive.js +++ b/templates/javascript/directive.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc directive + * @name <%= scriptAppName %>.directive:<%= cameledName %> + * @description + * # <%= cameledName %> + * Directive to replace content with custom text. + */ angular.module('<%= scriptAppName %>') .directive('<%= cameledName %>', function () { return { diff --git a/templates/javascript/filter.js b/templates/javascript/filter.js index 9f897ab76..7f27e2f73 100644 --- a/templates/javascript/filter.js +++ b/templates/javascript/filter.js @@ -1,5 +1,13 @@ 'use strict'; +/** + * @ngdoc filter + * @name <%= scriptAppName %>.filter:<%= cameledName %> + * @function + * @description + * # <%= cameledName %> + * Filter to change your value. + */ angular.module('<%= scriptAppName %>') .filter('<%= cameledName %>', function () { return function (input) { diff --git a/templates/javascript/service/constant.js b/templates/javascript/service/constant.js index 0c02a8a8a..e23d3435a 100644 --- a/templates/javascript/service/constant.js +++ b/templates/javascript/service/constant.js @@ -1,4 +1,11 @@ 'use strict'; +/** + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Constat in the <%= scriptAppName %>. + */ angular.module('<%= scriptAppName %>') .constant('<%= cameledName %>', 42); diff --git a/templates/javascript/service/factory.js b/templates/javascript/service/factory.js index f7e942eb9..51e9c17f8 100644 --- a/templates/javascript/service/factory.js +++ b/templates/javascript/service/factory.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Factory in the <%= scriptAppName %>. + */ angular.module('<%= scriptAppName %>') .factory('<%= cameledName %>', function () { // Service logic diff --git a/templates/javascript/service/provider.js b/templates/javascript/service/provider.js index 101e774c5..e72debb49 100644 --- a/templates/javascript/service/provider.js +++ b/templates/javascript/service/provider.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Provider in the <%= scriptAppName %>. + */ angular.module('<%= scriptAppName %>') .provider('<%= cameledName %>', function () { diff --git a/templates/javascript/service/service.js b/templates/javascript/service/service.js index 1adfe44b4..b5b5f9fd1 100644 --- a/templates/javascript/service/service.js +++ b/templates/javascript/service/service.js @@ -1,5 +1,12 @@ 'use strict'; +/** + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Service in the <%= scriptAppName %>. + */ angular.module('<%= scriptAppName %>') .service('<%= classedName %>', function <%= classedName %>() { // AngularJS will instantiate a singleton by calling "new" on this function diff --git a/templates/javascript/service/value.js b/templates/javascript/service/value.js index 01507e03f..67f107e2c 100644 --- a/templates/javascript/service/value.js +++ b/templates/javascript/service/value.js @@ -1,4 +1,11 @@ 'use strict'; +/** + * @ngdoc service + * @name <%= scriptAppName %>.<%= cameledName %> + * @description + * # <%= cameledName %> + * Value in the <%= scriptAppName %>. + */ angular.module('<%= scriptAppName %>') .value('<%= cameledName %>', 42);