dgeni-packages - npm Package Compare versions

Comparing version 0.3.1 to 0.4.0

CHANGELOG.md

@@ -0,3 +1,30 @@
+## 0.4.0 03/06/2014
+
+**New Features**
+
+* feat(examples): move injected example into a template  cc658f31
+* feat(jsdoc): add `rendering.nunjucks.config` field to config  eb805097
+* feat(link inline handler): replace old link processor with new inline handle  723e0e56
+* feat(inline-tag processor): add new generic inline tag processor  39083631
+* feat(firstParagraph filter): add new filter  4dcabba1
+* feat(jsdoc extractor): add esprima powered jsdoc extractor  e96da1ea
+
+**Bug Fixes**
+
+* fix(ngdoc/templates) : improve "View Source" and "Improve Doc" links  049ee59f
+* fix(write-files): ignore docs that have no output path  c666e5e3
+* fix(ngdoc templates): show first paragraph not first line  7335fd91
+
+**BREAKING CHANGE**
+
+* The `examples` injectable object has changed from being
+a flat array to a hash indexed on the id of the example.  If you only
+iterated over the examples then things like `forEach` should still just
+work.  But you can no longer access the examples by index, e.g.
+`examples[0]` will return undefined rather than the first example.
+
 ## 0.3.1 03/02/2014
 
+**Bug Fixes**
+
 * fix(tagParser): don't break on bad-tags  560eff7b
@@ -8,2 +35,4 @@
 
+**New Features**
+
 * feat(tagParser): ignore tags inside fenced code blocks   09fb7d64
@@ -13,2 +42,4 @@ * feat(trimProcessor): add tag processor to trim off whitespace  a81f6231
 
+**Bug Fixes**
+
 * fix(typeProcessor): handle escaped braces  786f1ab5
@@ -27,2 +58,4 @@ * fix(ngdoc templates): ensure type hints are escaped  4ace02b8
 
+**Bug Fixes**
+
 * fix(doctrine-tag-parser): don't rethrow error if tag type is bad  7ac46af6
@@ -32,2 +65,4 @@
 
+**Bug Fixes**
+
 * fix(doctrine-tag-parser): support jsdoc3 tags and improve error messages  c8ca67a2
@@ -37,2 +72,4 @@
 
+**Bug Fixes**
+
 * fix(examples-generate): ensure each index file gets content c4918e05
@@ -43,2 +80,4 @@ * fix(ngdoc/members): render member docs correctly  c7b98a67
 
+**Bug Fixes**
+
 * fix(example-generation): commonFiles should get scripts from the 'scripts' object  3b41c91a
@@ -48,2 +87,4 @@
 
+**New Features**
+
 * feat(example-generation): generate examples for multiple deployments  82ba9054
@@ -53,2 +94,4 @@
 
+**Bug Fixes**
+
 * fix(doc-extractor): give decent error if projectPath is missing 0e326692

examples/index.js

@@ -11,2 +11,6 @@ var path = require('canonical-path');
 
+  config.append('processing.inlineTagDefinitions', [
+    require('./inline-tag-defs/runnableExample')
+  ]);
+
   config.set('processing.examples.commonFiles', {
@@ -13,0 +17,0 @@ scripts: [],

examples/processors/examples-generate.js

@@ -68,10 +68,21 @@ var _ = require('lodash');
 
+function createRunnableExampleDoc(example) {
+  var exampleDoc = {
+    id: example.id + '-runnableExample',
+    docType: 'runnableExample',
+    file: example.doc.file,
+    startingLine: example.doc.startingLine,
+    example: example
+  };
+  return exampleDoc;
+}
 
 module.exports = {
   name: 'examples-generate',
-  description: 'Search the documentation for examples that need to be extracted',
+  description: 'Create doc objects of the various things that need to be rendered for an example.\n' +
+               'This includes the files that will be run in an iframe, the code that will be injected' +
+               'into the HTML pages and the protractor test files',
   runAfter: ['adding-extra-docs'],
   runBefore: ['extra-docs-added'],
   init: function(config, injectables) {
-    exampleNames = Object.create(null);
 
@@ -86,3 +97,3 @@ deployments = config.get('deployment.environments');
   process: function(docs, examples) {
-    _.forEach(examples, function(example) {
+    _.forOwn(examples, function(example) {
 
@@ -92,8 +103,10 @@ var stylesheets = [];
 
-      // We don't want to create a file for index.html, since that will be covered by the exampleDoc
+      // The index file is special, see createExampleDoc()
       example.indexFile = example.files['index.html'];
-      delete example.files['index.html'];
 
       // Create a new document for each file of the example
-      _.forEach(example.files, function(file) {
+      _(example.files)
+      // We don't want to create a file for index.html, see createExampleDoc()
+      .omit('index.html')
+      .forEach(function(file) {
 
@@ -111,3 +124,3 @@ var fileDoc = createFileDoc(example, file);
 
-      // Create a new document for the example (for each deployment)
+      // Create an index.html document for the example (one for each deployment type)
       _.forEach(deployments, function(deployment) {
@@ -117,4 +130,10 @@ var exampleDoc = createExampleDoc(example, deployment, stylesheets, scripts);
       });
+
+      // Create the doc that will be injected into the website as a runnable example
+      var runnableExampleDoc = createRunnableExampleDoc(example);
+      docs.push(runnableExampleDoc);
+      example.runnableExampleDoc = runnableExampleDoc;
+
     });
   }
 };

examples/processors/examples-parse.js

@@ -34,2 +34,3 @@ var _ = require('lodash');
     file.type = file.type || file.language || 'file';
+    file.attributes = _.omit(file, ['fileContents']);
 
@@ -42,7 +43,6 @@ // Store this file information
 
-var exampleNames;
-function uniqueName(name) {
-  if ( exampleNames[name] ) {
+var uniqueName = function(container, name) {
+  if ( container[name] ) {
     var index = 1;
-    while(exampleNames[name + index]) {
+    while(container[name + index]) {
       index += 1;
@@ -52,50 +52,5 @@ }
   }
-  exampleNames[name] = true;
   return name;
-}
+};
 
-function generateExampleDirective(example) {
-
-  var html = '';
-
-    // Be aware that we need these extra new lines here or marked will not realise that the <div>
-  // above is HTML and wrap each line in a <p> - thus breaking the HTML
-  html += '\n\n';
-  
-  // Write out the runnable-example directive
-  html += '<div class="runnable-example"';
-  _.forEach(_.omit(example, ['files', 'doc']), function(value, key) {
-    html += ' ' + key + '="' + value + '"';
-  });
-  html += '>\n';
-
-  // Write each of the files as a runnable-example-file directive
-  _.forEach(example.files, function(file) {
-    html += '<div class="runnable-example-file"';
-    _.forEach(_.omit(file, ['fileContents']), function(value, key) {
-      html += ' ' + key + '="' + value + '"';
-    });
-    html += '>\n\n';
-    
-    // We need to convert the code as markdown to ensure that it is HTML encoded
-    var code = '```' + (file.language || '') + '\n' + file.fileContents + '\n```\n\n';
-    // We must wrap the rendered HTML code in a div to ensure that it doesn't get parsed as markdown
-    // a second time later.
-    html += '\n\n<div>\n' + marked(code) + '\n</div>\n\n';
-
-    html += '</div>\n';
-  });
-
-  // Write out the iframe that will host the runnable example
-  html += '<iframe class="runnable-example-frame" src="' + example.outputFolder + '/index.html" name="' + example.id + '"></iframe>\n';
-
-  html += '</div>';
-
-  // Be aware that we need these extra new lines here or marked will not realise that the <div>
-  // above is HTML and wrap each line in a <p> - thus breaking the HTML
-  html += '\n\n';
-  
-  return html;
-}
-
 module.exports = {
@@ -108,5 +63,5 @@ name: 'examples-parse',
     // Reset the unique name map
-    exampleNames = Object.create(null);
+    examples = Object.create(null);
 
-    injectables.value('examples', []);
+    injectables.value('examples', examples);
 
@@ -120,4 +75,6 @@ outputFolder = config.get('processing.examples.outputFolder', 'examples');
         var example = extractAttributes(attributeText);
+        example.attributes = _.omit(example, ['files', 'doc']);
+        var id = uniqueName(examples, 'example-' + (example.name || 'example'));
         example.files = extractFiles(exampleText);
-        example.id = 'example-' + uniqueName(example.name || 'example');
+        example.id = id;
         example.doc = doc;
@@ -127,5 +84,6 @@ example.outputFolder = path.join(outputFolder, example.id);
         // store the example information for later
-        examples.push(example);
+        log.debug('Storing example', id);
+        examples[id] = example;
 
-        return generateExampleDirective(example);
+        return '{@runnableExample ' + id + '}';
       });
@@ -132,0 +90,0 @@ });

examples/spec/processors/examples-generate.spec.js

@@ -35,3 +35,3 @@ var plugin = require('../../processors/examples-generate');
     ];
-    examples = [
+    examples = { 'a.b.c':
       {
@@ -49,3 +49,3 @@ id: 'a.b.c',
       }
-    ];
+    };
 
@@ -97,2 +97,6 @@ plugin.process(docs, examples);
   });
+
+  it("should add a runnableExampleDoc for each example", function() {
+    var runnableExampleDocs = _.filter(docs, { docType: 'runnableExample' });
+  });
 });

examples/spec/processors/examples-parse.spec.js

@@ -5,2 +5,3 @@ var rewire = require('rewire');
 var log = require('winston');
+var _ = require('lodash');
 
@@ -21,3 +22,3 @@ describe("examples-parse doc processor", function() {
   it("should extract example tags from the doc content", function() {
-    var examples = [];
+    var examples = {};
     plugin.process([
@@ -34,13 +35,14 @@ {
     }], examples);
-    expect(examples[0]).toEqual(jasmine.objectContaining({ name:'bar', moo1:'nar1', files: {} , id: 'example-bar'}));
-    expect(examples[1]).toEqual(jasmine.objectContaining({ name:'bar', moo2:'nar2', files: {} , id: 'example-bar1'}));
-    expect(examples[2]).toEqual(jasmine.objectContaining({ name:'value', files: {}, id: 'example-value'}));
-    expect(examples[3]).toEqual(jasmine.objectContaining({
-      name: 'with-files',
-      files: {
-        'app.js': { name: 'app.js', fileContents: 'aaa', language: 'js', type: 'js' },
-        'app.spec.js': { name: 'app.spec.js', fileContents: 'bbb', language: 'js', type: 'spec' },
-      },
-      id: 'example-with-files'
-    }));
+    expect(examples['example-bar']).toEqual(jasmine.objectContaining({ name:'bar', moo1:'nar1', id: 'example-bar'}));
+    expect(examples['example-bar1']).toEqual(jasmine.objectContaining({ name:'bar', moo2:'nar2', id: 'example-bar1'}));
+    expect(examples['example-value']).toEqual(jasmine.objectContaining({ name:'value', id: 'example-value'}));
+    expect(examples['example-with-files']).toEqual(jasmine.objectContaining({ name: 'with-files', id: 'example-with-files'}));
+
+    // Jasmine doesn't like that the files property hasn't got a hasOwnProperty method because it was created using Object.create(null);
+    // So we map it into something else
+    var files = _.map(examples['example-with-files'].files, function(file) { return _.clone(file); });
+    expect(files).toEqual([
+      jasmine.objectContaining({ name: 'app.js', type: 'js', fileContents: 'aaa', language: 'js' }),
+      jasmine.objectContaining({ name: 'app.spec.js', type: 'spec', fileContents: 'bbb', language: 'js' })
+    ]);
   });
@@ -55,4 +57,4 @@
     }], examples);
-    expect(examples[0].id).toEqual('example-bar');
-    expect(examples[1].id).toEqual('example-bar1');
+    expect(examples['example-bar'].id).toEqual('example-bar');
+    expect(examples['example-bar1'].id).toEqual('example-bar1');
   });
@@ -62,3 +64,3 @@
     doc = {
-      content: '<example name="bar">some example content 1</example>'
+      content: 'Some content before <example name="bar">some example content 1</example> and some after'
     };
@@ -68,4 +70,3 @@
 
-    expect(doc.content).toMatch('<div class="runnable-example" name="bar" id="example-bar" outputFolder="examples/example-bar">');
-    expect(doc.content).toMatch('<iframe class="runnable-example-frame" src="examples/example-bar/index.html" name="example-bar"></iframe>');
+    expect(doc.content).toEqual('Some content before {@runnableExample example-bar} and some after');
 
@@ -72,0 +73,0 @@ });

jsdoc/index.js

@@ -11,4 +11,6 @@ module.exports = function(config) {
     require('./processors/escaped-comments'),
+    require('./processors/inline-tags'),
     require('./processors/write-files')
   ]);
+  
   config.append('processing.tagDefinitions', require('./tag-defs'));
@@ -19,2 +21,3 @@
     require('./rendering/filters/first-line'),
+    require('./rendering/filters/first-paragraph'),
     require('./rendering/filters/json'),
@@ -21,0 +24,0 @@ require('./rendering/filters/marked')

jsdoc/processors/nunjucks-renderer.js

@@ -33,3 +33,3 @@ var _ = require('lodash');
     env = new nunjucks.Environment(new nunjucks.FileSystemLoader(config.rendering.templateFolders, true),
-      { tags: { variableStart: '{$', variableEnd: '$}' } }
+      config.get('rendering.nunjucks.config', {})
     );
@@ -73,2 +73,2 @@
   }
-};
+};

jsdoc/processors/write-files.js

@@ -21,15 +21,16 @@ var _ = require('lodash');
       if ( !doc.outputPath ) {
-        console.log(doc);
-        log.error('Invalid document "' + doc.id + ', ' + doc.docType + '" - this document has no outputPath.');
-      }
+        log.debug('Document "' + doc.id + ', ' + doc.docType + '" has no outputPath.');
+      } else {
 
-      var outputFile = path.resolve(outputFolder, doc.outputPath);
+        var outputFile = path.resolve(outputFolder, doc.outputPath);
 
-      log.silly('writing file', outputFile);
-      return writer.writeFile(outputFile, doc.renderedContent).then(function() {
-        log.debug('written file', outputFile);
-        return outputFile;
-      });
+        log.silly('writing file', outputFile);
+        return writer.writeFile(outputFile, doc.renderedContent).then(function() {
+          log.debug('written file', outputFile);
+          return outputFile;
+        });
+
+      }
     }));
   }
 };

jsdoc/spec/processors/nunjucks-renderer.spec.js

 var rewire = require('rewire');
 var plugin = rewire('../../processors/nunjucks-renderer');
+var config = require('dgeni/lib/utils/config').Config;
 
@@ -16,2 +17,9 @@ describe("doc-renderer", function() {
     nunjucks.Environment.prototype.addExtension = addExtensionSpy;
+
+    config.set('basePath', '/');
+    config.set('rendering', {
+      templateFolders: ['templates'],
+      templatePatterns: [],
+      outputFolder: 'output'
+    });
   });
@@ -21,11 +29,11 @@
 
+    var nunjucksConfig = { foo: 'bar' };
+    config.set('rendering.nunjucks.config', nunjucksConfig);
 
-    plugin.init({ basePath: '/', rendering: { templateFolders: ['templates'], templatePatterns: [], outputFolder: 'output' }}, injectables);
+    plugin.init(config, injectables);
 
-    expect(nunjucks.Environment).toHaveBeenCalledWith(jasmine.any(nunjucks.FileSystemLoader), {
-      tags: {
-        variableStart: '{$',
-        variableEnd: '$}'
-      }
-    });
+    expect(nunjucks.Environment).toHaveBeenCalledWith(
+      jasmine.any(nunjucks.FileSystemLoader), 
+      nunjucksConfig
+    );
   });
@@ -37,7 +45,10 @@
 
-    plugin.init({ basePath: '/', rendering: { templateFolders: ['templates'], templatePatterns: [], outputFolder: 'output', filters: [dummyFilter],  tags: [dummyExtension] } }, injectables);
+    config.set('rendering.filters', [dummyFilter]);
+    config.set('rendering.tags', [dummyExtension]);
 
+    plugin.init(config, injectables);
+
     expect(addFilterSpy).toHaveBeenCalledWith(dummyFilter.name, dummyFilter.process);
     expect(addExtensionSpy).toHaveBeenCalledWith('dummy', dummyExtension);
   });
-});
+});

ngdoc/index.js

@@ -7,2 +7,6 @@ var path = require('canonical-path');
 
+  config.merge('rendering.nunjucks.config.tags', {
+    variableStart: '{$',
+    variableEnd: '$}'
+  });
   config = basePackage(config);
@@ -13,2 +17,5 @@
   config.append('processing.tagDefinitions', require('./tag-defs'));
+  config.append('processing.inlineTagDefinitions', [
+    require('./inline-tag-defs/link')
+  ]);
 
@@ -19,4 +26,3 @@ config.append('processing.processors', [
     require('./processors/api-docs'),
-    require('./processors/component-groups-generate'),
-    require('./processors/links')
+    require('./processors/component-groups-generate')
   ]);
@@ -47,2 +53,2 @@
   return config;
-};
+};

package.json

 {
   "name": "dgeni-packages",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A collection of dgeni packages for generating documentation from source code",
@@ -33,3 +33,3 @@ "scripts": {
   "dependencies": {
-    "dgeni": "~0.2.0",
+    "dgeni": "~0.2.1",
     "canonical-path": "0.0.2",
@@ -43,11 +43,18 @@ "lodash": "~2.4.1",
     "nunjucks": "~1.0.1",
-    "catharsis": "^0.7.0"
+    "catharsis": "^0.7.0",
+    "esprima": "^1.0.4"
   },
   "peerDependencies": {
-    "dgeni": "~0.2.0"
+    "dgeni": "~0.2.1"
   },
   "devDependencies": {
     "rewire": "~2.0.0",
-    "jasmine-node": "~1.13.1"
-  }
+    "jasmine-node": "~1.13.1",
+    "di": "~0.0.1"
+  },
+  "contributors": [
+    "Peter Bacon Darwin <[e-mail]>",
+    "Andy Joslin <[e-mail]>",
+    "Julie <[e-mail]>"
+  ]
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

145805

increased by9.02%

Number of package files

113

increased by7.62%

Lines of code

3200

increased by7.74%

Worsened metrics

Dependency count

12

increased by9.09%

Dev dependency count

3

increased by50%

Dependency changes

• + Addedesprima@^1.0.4

• + Addedesprima@1.2.5(transitive)

• Updateddgeni@~0.2.1