feat(gen) add grunt-ngdoc

marcin-wosinek · marcin-wosinek · commit ef01195079f4 · 2014-02-16T21:55:21.000Z
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 yeoman#550
diff --git 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: '/'
-<% } %>
+<% } %>
diff --git 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
@@ -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
@@ -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: '<div></div>'
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,4 +1,11 @@
 'use strict';
 
+/**
+ * @ngdoc service
+ * @name <%= scriptAppName %>.<%= cameledName %>
+ * @description
+ * # <%= cameledName %>
+ * Value in the <%= scriptAppName %>.
+ */
 angular.module('<%= scriptAppName %>')
   .value('<%= cameledName %>', 42);
