grunt-ngdocs - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

CHANGELOG.md

@@ -0,1 +1,43 @@
+# 0.1.2 (2013-06-27)
+
+## Features
+
+### global
+
+* add module name to none overview module page ([5b58367a](https://github.com/m7r/grunt-ngdocs/commit/5b58367a))
+
+* allow multiple API sections or custom name for API section ([3ebc5153](https://github.com/m7r/grunt-ngdocs/commit/3ebc5153))
+
+* make start page configurable #8 ([5e764f54](https://github.com/m7r/grunt-ngdocs/commit/5e764f54))
+
+* allow additional custom types ([df3103be](https://github.com/m7r/grunt-ngdocs/commit/df3103be))
+
+### docs
+
+* make remote css files work ([2d4e2aeb](https://github.com/m7r/grunt-ngdocs/commit/2d4e2aeb))
+
+* show section title in breadcrum ([5b4e1a71](https://github.com/m7r/grunt-ngdocs/commit/5b4e1a71))
+
+
+## Bug fixes
+
+### global
+
+* name overview pages for modules with dots correctly #13 ([c804b1d1](https://github.com/m7r/grunt-ngdocs/commit/c804b1d1))
+
+* build ngdocs on windows #17 ([27a884aa](https://github.com/m7r/grunt-ngdocs/commit/27a884aa))
+
+
+### ngdocs
+
+* remove hardcoded section 'api' for js files ([951db22e](https://github.com/m7r/grunt-ngdocs/commit/951db22e))
+
+### docs
+
+* take out 'IE restrictions' warning ([a376ff3c](https://github.com/m7r/grunt-ngdocs/commit/a376ff3c))
+
+* search form submit load page in both url modes ([183f67ce](https://github.com/m7r/grunt-ngdocs/commit/183f67ce))
+
+
+
 # 0.1.1 (2013-06-01)
@@ -2,0 +44,0 @@

package.json

 {
   "name": "grunt-ngdocs",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "grunt plugin for angularjs documentation",
@@ -27,4 +27,4 @@ "main": "tasks",
     "grunt": "~0.4.1",
-    "grunt-conventional-changelog": "~0.0.10"
+    "grunt-conventional-changelog": "~0.1.0"
   }
 }

README.md

@@ -16,2 +16,4 @@ #grunt-ngdocs
 
+A full working example can be found at [https://github.com/m7r/grunt-ngdocs-example]()
+
 ##Config
@@ -35,2 +37,3 @@ Inside your `Gruntfile.js` file, add a section named *ngdocs*.
     html5Mode: true,
+    startPage: '/api',
     title: "My Awesome Docs",
@@ -90,2 +93,6 @@ analytics: {
 
+####startPage
+[default] '/api'
+Set first page to open. 
+
 ####html5Mode
@@ -125,3 +132,7 @@ [default] 'true'
 
+####api
+[default] true for target api  
+Set the sidebar to advanced mode with sections for modules, services etc.
 
+
 ##How it works
@@ -128,0 +139,0 @@ The task parses the specified files for doc commets and extract these in partial html files for the documentation app.

src/ngdoc.js

@@ -318,3 +318,3 @@ /**
 
-    dom.h(title(this.name), function() {
+    dom.h(title(this.name, this.ngdoc == 'overview'), function() {
 
@@ -413,7 +413,7 @@ notice('deprecated', 'Deprecated API', self.deprecated);
     var self = this;
-    var name = self.name.match(/^angular(\.mock)?\.(\w+)$/) ? self.name : self.name.split(/\./).pop()
+    var name = self.name.match(/^angular(\.mock)?\.(\w+)$/) ? self.name : self.name.split(/\./).pop();
 
     dom.h('Usage', function() {
       dom.code(function() {
-        dom.text(name);
+        dom.text(name.split(':').pop());
         dom.text('(');
@@ -447,9 +447,9 @@ self.parameters(dom, ', ');
 
-      if (restrict.match(/E/)) {
+      /*if (restrict.match(/E/)) {
         dom.html('<p>');
         dom.text('This directive can be used as custom element, but be aware of ');
-        dom.tag('a', {href:'guide/ie'}, 'IE restrictions');
+        dom.tag('a', {href:'http://docs.angularjs.org/guide/ie'}, 'IE restrictions');
         dom.text('.');
         dom.html('</p>');
-      }
+      }*/
 
@@ -752,3 +752,3 @@ if (self.usage) {
     MODULE_DIRECTIVE_INPUT = /^(.+)\.directive:input\.([^\.]+)$/,
-    MODULE_FILTER = /^(.+)\.filter:([^\.]+)$/,
+    MODULE_CUSTOM = /^(.+)\.([^\.]+):([^\.]+)$/,
     MODULE_SERVICE = /^(.+)\.([^\.]+?)(Provider)?$/,
@@ -758,3 +758,3 @@ MODULE_TYPE = /^([^\.]+)\..+\.([A-Z][^\.]+)$/;
 
-function title(text) {
+function title(text, overview) {
   if (!text) return text;
@@ -776,2 +776,3 @@ var match,
     module = match[1];
+    if (!overview) { name = match[1]; }
   } else if (match = text.match(MODULE_MOCK)) {
@@ -789,6 +790,6 @@ module = 'ng';
     type = 'directive';
-  } else if (match = text.match(MODULE_FILTER)) {
+  } else if (match = text.match(MODULE_CUSTOM)) {
     module = match[1];
-    name = match[2];
-    type = 'filter';
+    name = match[3];
+    type = match[2];
   } else if (match = text.match(MODULE_TYPE)) {
@@ -799,5 +800,10 @@ module = match[1];
   } else if (match = text.match(MODULE_SERVICE)) {
-    module = match[1];
-    name = match[2] + (match[3] || '');
-    type = 'service';
+    if (overview) {
+      // module name with dots looks like a service
+      module = text;
+    } else {
+      module = match[1];
+      name = match[2] + (match[3] || '');
+      type = 'service';
+    }
   } else {
@@ -804,0 +810,0 @@ return text;

src/reader.js

@@ -13,3 +13,3 @@ /**
   if (/\.js$/.test(file)) {
-    processJsFile(content, file).forEach(function(doc) {
+    processJsFile(content, file, section).forEach(function(doc) {
       exports.docs.push(doc);
@@ -23,3 +23,3 @@ });
 
-function processJsFile(content, file) {
+function processJsFile(content, file, section) {
   var docs = [];
@@ -47,3 +47,3 @@ var lines = content.toString().split(NEW_LINE);
         //console.log(file, startingLine)
-        docs.push(new ngdoc.Doc('@section api\n' + text, file, startingLine).parse());
+        docs.push(new ngdoc.Doc('@section ' + section + '\n' + text, file, startingLine).parse());
       }
@@ -50,0 +50,0 @@ doc = null;

src/templates/js/docs.js

@@ -268,3 +268,3 @@ var docsApp = {
     } else {
-      page.partialUrl = 'partials/' + url + '.html';
+      page.partialUrl = 'partials/' + url.replace(':', '.') + '.html';
     }
@@ -288,2 +288,3 @@ page.url = (NG_DOCS.html5Mode ? '' : '#/') + url;
       MODULE_FILTER = /^(.+)\.filter:([^\.]+)$/,
+      MODULE_CUSTOM = /^(.+)\.([^\.]+):([^\.]+)$/,
       MODULE_SERVICE = /^(.+)\.([^\.]+?)(Provider)?$/,
@@ -312,3 +313,6 @@ MODULE_TYPE = /^([^\.]+)\..+\.([A-Z][^\.]+)$/;
   $scope.submitForm = function() {
-    $scope.bestMatch && $location.path($scope.bestMatch.page.url);
+    if ($scope.bestMatch) {
+      var url =  $scope.bestMatch.page.url;
+      $location.path(NG_DOCS.html5Mode ? url : url.substring(1));
+    }
   };
@@ -353,3 +357,3 @@
     if (partialId) {
-      breadcrumb.push({ name: sectionName, url: sectionPath });
+      breadcrumb.push({ name: NG_DOCS.sections[sectionName], url: sectionPath });
       if (partialId == 'angular.Module') {
@@ -371,2 +375,5 @@ breadcrumb.push({ name: 'angular.Module' });
         breadcrumb.push({ name: match[2] });
+      } else if (match = partialId.match(MODULE_CUSTOM)) {
+        breadcrumb.push({ name: match[1], url: sectionPath + '/' + match[1] });
+        breadcrumb.push({ name: match[3] });
       } else if (match = partialId.match(MODULE_TYPE)) {
@@ -376,4 +383,9 @@ breadcrumb.push({ name: match[1], url: sectionPath + '/' + match[1] });
       }  else if (match = partialId.match(MODULE_SERVICE)) {
-        breadcrumb.push({ name: match[1], url: sectionPath + '/' + match[1] });
-        breadcrumb.push({ name: match[2] + (match[3] || '') });
+        if ( page.type === 'overview') {
+          // module name with dots looks like a service
+          breadcrumb.push({ name: partialId });
+        } else {
+          breadcrumb.push({ name: match[1], url: sectionPath + '/' + match[1] });
+          breadcrumb.push({ name: match[2] + (match[3] || '') });
+        }
       } else if (match = partialId.match(MODULE_MOCK)) {
@@ -385,3 +397,3 @@ breadcrumb.push({ name: 'angular.mock.' + match[1] });
     } else {
-      breadcrumb.push({ name: sectionName });
+      breadcrumb.push({ name: NG_DOCS.sections[sectionName] });
     }
@@ -405,3 +417,3 @@ });
   if (!$location.path() || INDEX_PATH.test($location.path())) {
-    $location.path('/api').replace();
+    $location.path(NG_DOCS.startPage).replace();
   }
@@ -431,3 +443,4 @@ // bind escape to hash reset callback
       var match,
-        id = page.id;
+        id = page.id,
+        section = page.section;
 
@@ -442,22 +455,28 @@ if (!(match = rank(page, search))) return;
         //skip
-      } else if (page.section != 'api') {
+      } else if (!NG_DOCS.apis[section]) {
         otherPages.push(page);
       } else if (id == 'angular.Module') {
-        module('ng').types.push(page);
+        module('ng', section).types.push(page);
       } else if (match = id.match(GLOBALS)) {
-        module('ng').globals.push(page);
+        module('ng', section).globals.push(page);
       } else if (match = id.match(MODULE)) {
-        module(match[1]);
+        module(match[1], section);
       } else if (match = id.match(MODULE_FILTER)) {
-        module(match[1]).filters.push(page);
+        module(match[1], section).filters.push(page);
       } else if (match = id.match(MODULE_DIRECTIVE)) {
-        module(match[1]).directives.push(page);
+        module(match[1], section).directives.push(page);
       } else if (match = id.match(MODULE_DIRECTIVE_INPUT)) {
-        module(match[1]).directives.push(page);
+        module(match[1], section).directives.push(page);
+      } else if (match = id.match(MODULE_CUSTOM)) {
+        module(match[1], section).others.push(page);
       } else if (match = id.match(MODULE_TYPE)) {
-        module(match[1]).types.push(page);
+        module(match[1], section).types.push(page);
       } else if (match = id.match(MODULE_SERVICE)) {
-        module(match[1]).service(match[2])[match[3] ? 'provider' : 'instance'] = page;
+        if (page.type === 'overview') {
+          module(id, section);
+        } else {
+          module(match[1], section).service(match[2])[match[3] ? 'provider' : 'instance'] = page;
+        }
       } else if (match = id.match(MODULE_MOCK)) {
-        module('ngMock').globals.push(page);
+        module('ngMock', section).globals.push(page);
       }
@@ -471,3 +490,3 @@
 
-    function module(name) {
+    function module(name, section) {
       var module = cache[name];
@@ -477,6 +496,7 @@ if (!module) {
           name: name,
-          url: (NG_DOCS.html5Mode ? '' : '#/') + 'api/' + name,
+          url: (NG_DOCS.html5Mode ? '' : '#/') + section + '/' + name,
           globals: [],
           directives: [],
           services: [],
+          others: [],
           service: function(name) {
@@ -483,0 +503,0 @@ var service =  cache[this.name + ':' + name];

tasks/grunt-ngdocs.js

@@ -23,2 +23,3 @@ /*
           dest: 'docs/',
+          startPage: '/api',
           scripts: ['angular.js'],
@@ -63,5 +64,9 @@ styles: [],
     options.styles = _.map(options.styles, function(file) {
-      var filename = file.split('/').pop();
-      grunt.file.copy(file, path.join(options.dest, 'css', filename));
-      return 'css/' + filename;
+      if (/^((https?:)?\/\/|\.\.\/)/.test(file)) {
+        return file;
+      } else {
+        var filename = file.split('/').pop();
+        grunt.file.copy(file, path.join(options.dest, 'css', filename));
+        return 'css/' + filename;
+      }
     });
@@ -76,2 +81,3 @@
       setup.sections[section] = f.title || 'API Documentation';
+      setup.apis[section] = f.api || section == 'api';
       f.src.filter(exists).forEach(function(filepath) {
@@ -87,3 +93,3 @@ var content = grunt.file.read(filepath);
       // this hack is here because on OSX angular.module and angular.Module map to the same file.
-      var id = doc.id.replace('angular.Module', 'angular.IModule'),
+      var id = doc.id.replace('angular.Module', 'angular.IModule').replace(':', '.'),
           file = path.resolve(options.dest, 'partials', doc.section, id + '.html');
@@ -119,3 +125,3 @@ grunt.file.write(file, doc.html());
       // build clean dest
-      setup = {sections: {}, pages: []};
+      setup = {sections: {}, pages: [], apis: {}};
       copyTemplates(options.dest);
@@ -150,2 +156,3 @@ }
     setup.html5Mode = options.html5Mode;
+    setup.startPage = options.startPage;
     setup.discussions = options.discussions;
@@ -152,0 +159,0 @@ setup.scripts = _.map(options.scripts, function(url) { return path.basename(url); });

No alert changes

Improved metrics

Total package byte prevSize

692769

increased by0.48%

Lines of code

9207

increased by0.39%

Number of lines in readme file

172

increased by6.83%

No dependency changes