dgeni - npm Package Compare versions

Comparing version 0.2.2 to 0.3.0

bin/gen-docs.js

 #!/usr/bin/env node
-var log = require('winston');
 var rimraf = require('rimraf');
@@ -8,25 +7,23 @@ var myArgs = require('optimist')
   .argv;
-var configurer = require('../lib/utils/config');
-var docGenerator = require('../lib/index');
 
+var dgeni = require('../lib/index');
+var log = dgeni.log;
+
+// Set up logging to look nice on the command line
 log.cli();
 
 // Load in the config file and run it over the top of the default config
-var config = configurer.load(myArgs._[0]);
+var config = dgeni.loadConfig(myArgs._[0]);
 
-log.level = config.logging.level;
-log.info('Read config from "' + myArgs._[0] + '"');
-log.info('Logging set to "' + log.level + '"');
-log.debug('basePath: ', config.basePath);
+var outputFolder = config.get('rendering.outputFolder');
+if ( config.get('rendering.cleanOutputFolder') && outputFolder ) {
+  // Delete the previous output
+  rimraf.sync(outputFolder);
+  log.info('Removed previous output files from "' + outputFolder + '"');
+}
 
+var generateDocs = dgeni.generator(config);
 
-
-// Delete the previous output folder
-if ( config.rendering.cleanOutputFolder ) {
-  rimraf.sync(config.rendering.outputFolder);
-  log.info('Removed previous output files from "' + config.rendering.outputFolder + '"');
-}
-
-docGenerator(config).generateDocs().then(function() {
+generateDocs().then(function() {
   log.info('Finished generating docs');
 }).done();

CHANGELOG.md

 # ChangeLog
 
+## v0.3.0 (11th April 2014)
+
+This is a "Spring Clean" release
+
+* Configuration, utilities and dependencies that were only used by separate Dgeni packages have
+  been moved to those repositories.
+* There is an initial set of "guide" documents to read at
+  https://github.com/angular/dgeni/tree/master/docs/en_GB/guide.
+* The API has been cleaned up to make it easier to use Dgeni without having to look inside.
+
+** New Stuff **
+
+* feat(doc-processor): processors can declare injectable exports  cfd19f08
+
+** Breaking Changes **
+
+* refactor(index): provide a cleaner API surface  3c78776d
+* refact(doc-processor): move pseudo processors to dgeni-packages  c198f651
+
+
 ## v0.2.2 (6th March 2014)
@@ -4,0 +24,0 @@

lib/doc-processor.js

@@ -8,5 +8,16 @@ var _ = require('lodash');
 /**
- * Build a function to process the documents by running the given processors
+ */
+
+/**
+ * A factory that returns a function to process the documents.  This is achieved by passing each of the
+ * documents through a pipe-line of processors.  The processors to include in the pipe-line are specified
+ * in the `config` object under the `config.processing.processors` property.
+ *
+ * Each processor can modify, remove and add documents.  Typically, the initial processors will read in
+ * docs from some file source, then various transformations and manipulations will occur before the
+ * documents are rendered and written out into the actual documentation files.
+ *
+ * @module doc-processor
  * @param  {object} config   A configuration object that defines things like processors
- * @return {function}         The function that will process the docs
+ * @return {function()}         The function that will process the docs
  */
@@ -19,18 +30,3 @@ module.exports = function docProcessorFactory(config) {
 
-  var processors =  config.processing.processors.concat([
-    { name: 'loading-files' },
-    { name: 'files-loaded', runAfter: ['loading-files'] },
-    { name: 'parsing-tags', runAfter: ['files-loaded'] },
-    { name: 'tags-parsed', runAfter: ['parsing-tags'] },
-    { name: 'extracting-tags', runAfter: ['tags-parsed'] },
-    { name: 'tags-extracted', runAfter: ['extracting-tags'] },
-    { name: 'processing-docs', runAfter: ['tags-extracted'] },
-    { name: 'docs-processed', runAfter: ['processing-docs'] },
-    { name: 'adding-extra-docs', runAfter: ['docs-processed'] },
-    { name: 'extra-docs-added', runAfter: ['adding-extra-docs'] },
-    { name: 'rendering-docs', runAfter: ['extra-docs-added'] },
-    { name: 'docs-rendered', runAfter: ['rendering-docs'] },
-    { name: 'writing-files', runAfter: ['docs-rendered'] },
-    { name: 'files-written', runAfter: ['writing-files'] }
-  ]);
+  var processors = config.processing.processors;
 
@@ -79,11 +75,11 @@
 
-  // This function will create a child injector that has a reference to the injector itself
-  // and also to the docs object, if provided
-  function createChildInjector(baseInjector, docs) {
-    var module = new di.Module();
-    module.factory('injector', function() { return baseInjector; });
-    if ( docs ) { module.value('docs', docs); }
-    return new di.Injector([module], baseInjector);
-  }
+  var diModules = [injectables];
 
+  // Ådd the exports for each processor into the injector
+  _.forEach(processors, function getInjectables(processor) {
+    if ( processor.exports ) {
+      diModules.push(processor.exports);
+    }
+  });
+
   // Initialize the processors, passing them the config object
@@ -98,4 +94,14 @@ // and the injectables, so they can register new things with the injector
 
-  baseInjector = new di.Injector([injectables]);
+  baseInjector = new di.Injector(diModules);
 
+
+  // This function will create a child injector that has a reference to the injector itself
+  // and also to the docs object, if provided
+  function createChildInjector(baseInjector, docs) {
+    var module = new di.Module();
+    module.factory('injector', function() { return baseInjector; });
+    if ( docs ) { module.value('docs', docs); }
+    return new di.Injector([module], baseInjector);
+  }
+
   /**
@@ -106,3 +112,3 @@ * Process the docs
    */
-  return function(docs) {
+  return function process(docs) {
 
@@ -141,2 +147,2 @@ docs = docs || [];
   };
-};
+};

lib/index.js

@@ -1,37 +0,9 @@
-var _ = require('lodash');
-var log = require('winston');
-var configurer = require('../lib/utils/config');
-var docProcessorFactory = require('../lib/doc-processor');
-
-module.exports = function docGeneratorFactory(config) {
-
-  if ( _.isString(config) ) {
-    config = configurer.load(config);
-  }
-  if ( !_.isObject(config) || !_.isFunction(config.applyTo) ) {
-    throw new Error(
-      'Invalid configuration.  The config parameter must be a configuration object\n' +
-      'or a string pointing to a nodeJS module of the form:\n' +
-      'module.exports = function(config) {\n' +
-      '  ...\n' +
-      '  return config;\n' +
-      '};'
-    );
-  }
-
-  log.cli();
-  log.level = config.logging.level;
-  log.debug('basePath: ', config.basePath);
-  log.debug('Initializing components');
-
-  var processDocs = docProcessorFactory(config);
-
-  return {
-    generateDocs: function() {
-      log.info('Processing docs');
-      return processDocs().then(function(docs) {
-        log.info('Processed', docs.length, 'docs');
-      });
-    }
-  };
+/**
+ * @module dgeni
+ */
+module.exports = {
+  log: require('winston'),
+  Config: require('./config').Config,
+  loadConfig: require('./config').load,
+  generator: require('./doc-generator')
 };

package.json

 {
   "name": "dgeni",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Flexible JavaScript documentation generator used by AngularJS",
   "main": "lib/index.js",
   "scripts": {
-    "test": "node ./node_modules/jasmine-node/bin/jasmine-node spec",
-    "cover": "istanbul cover ./node_modules/jasmine-node/bin/jasmine-node -- spec"
+    "test": "jasmine-node spec",
+    "cover": "istanbul cover jasmine-node -- spec"
   },
@@ -29,11 +29,8 @@ "repository": {
     "di": "0.0.1",
-    "node-html-encoder": "0.0.2",
-    "canonical-path": "~0.0.2",
-    "q-io": "~1.10.6",
-    "marked": "~0.2.10",
-    "glob": "~3.2.7"
+    "canonical-path": "~0.0.2"
   },
   "devDependencies": {
     "jasmine-node": "~1.12.0",
-    "rewire": "~2.0.0"
+    "rewire": "~2.0.0",
+    "istanbul": "^0.2.7"
   },
@@ -44,3 +41,4 @@ "contributors": [
     "Pascal Precht",
-    "Jeff Cross"
+    "Jeff Cross",
+    "Stéphane Reynaud"
   ],
@@ -47,0 +45,0 @@ "bugs": {

README.md

@@ -1,2 +0,2 @@
-# Dgeni - Documentation Generator
+# Dgeni - Documentation Generator [![Build Status](https://travis-ci.org/angular/dgeni.svg?branch=master)](https://travis-ci.org/angular/dgeni)
 
@@ -7,18 +7,16 @@ The node.js documentation generation utility by angular.js and other projects.
 
-To get started, install the dependencies and then try out the example.
+Try out the Dgeni example project at https://github.com/petebacondarwin/dgeni-example
 
-## Install Dependencies
+## Installation
 
 You'll need node.js and a bunch of npm modules installed to run this tool.  Get node.js from here:
-http://nodejs.org/.  Then, in the root folder of the project run:
+http://nodejs.org/.  Then, in your project folder run:
 
 ```
-npm install
+npm install dgeni --save
 ```
 
-This will install the npm modules needed for documentation generation.  If you want to run the
-example you'll need to install more dependencies - see below.
+This will install Dgeni and any modules that Dgeni depends upon.
 
 
-
 ## Architecture
@@ -25,0 +23,0 @@

spec/doc-processor.spec.js

@@ -59,2 +59,29 @@ var Q = require('q');
 
+  it("should add exports to the di module", function() {
+    var processCalled = false;
+    var process = function(export1, export2) {
+      expect(export1).toEqual('export1 value');
+      expect(export2).toEqual('export2 vqlue');
+      processCalled = true;
+    };
+    var config = {
+      processing: {
+        processors: [
+          {
+            name: 'test-processor',
+            exports: {
+              export1: [ 'value', 'export1 value'],
+              export2: [ 'factory', function() { return 'export2 value'; }]
+            },
+            process: process
+          }
+        ]
+      }
+    };
+    var processDocs = docProcessorFactory(config);
+    return processDocs([]).then(function() {
+      expect(processCalled).toEqual(true);
+    });
+  });
+
   it("should call each of the processors in turn, passing the docs object to each", function() {
@@ -96,3 +123,2 @@ var log = [], docs = [ { content: 'a'}, { content: 'b'}];
         process = docProcessorFactory({ processing: {stopOnError: true,  processors: [badProcessor]} });
-        spyOn(log, 'error');
         var error;
@@ -110,3 +136,2 @@ return process([doc])
         process = docProcessorFactory({ processing: {stopOnError: false,  processors: [badProcessor]} });
-        spyOn(log, 'error');
         var error;
@@ -113,0 +138,0 @@ return process([doc])

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

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

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

56674

increased by12.32%

Dependency count

8

decreased by-33.33%

Number of package files

57

increased by103.57%

Number of low supply chain risk alerts

1

decreased by-50%

Worsened metrics

Dev dependency count

3

increased by50%

Lines of code

657

decreased by-35.53%

Number of lines in readme file

79

decreased by-2.47%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• - Removedglob@~3.2.7

• - Removedmarked@~0.2.10

• - Removednode-html-encoder@0.0.2

• - Removedq-io@~1.10.6

• - Removedcollections@0.2.2(transitive)

• - Removedglob@3.2.11(transitive)

• - Removedinherits@2.0.4(transitive)

• - Removedlru-cache@2.7.3(transitive)

• - Removedmarked@0.2.10(transitive)

• - Removedmimeparse@0.1.4(transitive)

• - Removedminimatch@0.3.0(transitive)

• - Removednode-html-encoder@0.0.2(transitive)

• - Removedq-io@1.10.9(transitive)

• - Removedqs@0.1.0(transitive)

• - Removedsigmund@1.0.1(transitive)

• - Removedurl2@0.0.0(transitive)

• - Removedweak-map@1.0.0(transitive)