chore(docs build): add flag to control log output level

closes #1823

Gulp targets like `check-deploy` and `serve-and-sync-devguide` are
quite verbose. This PR allows the `dgeni` logging level to be
controlled using the `--dgeni-log` flag. E.g., use `--dgen-log="error"`
to see only errors.

Also sets log level to "error" when gulp is silent
and log level for createShredMapPackage

Author: chalin

gulpfile.js

@@ -46,22 +46,27 @@ var exampleZipper = require(path.resolve(TOOLS_PATH, '_example-zipper/exampleZip
 var plunkerBuilder = require(path.resolve(TOOLS_PATH, 'plunker-builder/plunkerBuilder'));
 var fsUtils = require(path.resolve(TOOLS_PATH, 'fs-utils/fsUtils'));
 
+const isSilent = !!argv.silent;
+if (isSilent) gutil.log = gutil.noop;
+const _dgeniLogLevel = argv.dgeniLog || (isSilent ? 'error' : 'info');
 
 var _devguideShredOptions =  {
   examplesDir: path.join(DOCS_PATH, '_examples'),
   fragmentsDir: path.join(DOCS_PATH, '_fragments'),
-  zipDir: path.join(RESOURCES_PATH, 'zips')
+  zipDir: path.join(RESOURCES_PATH, 'zips'),
+  logLevel: _dgeniLogLevel
 };
 
 var _devguideShredJadeOptions =  {
-  jadeDir: DOCS_PATH
-
+  jadeDir: DOCS_PATH,
+  logLevel: _dgeniLogLevel
 };
 
 var _apiShredOptions =  {
   examplesDir: path.join(ANGULAR_PROJECT_PATH, 'modules/@angular/examples'),
   fragmentsDir: path.join(DOCS_PATH, '_fragments/_api'),
-  zipDir: path.join(RESOURCES_PATH, 'zips/api')
+  zipDir: path.join(RESOURCES_PATH, 'zips/api'),
+  logLevel: _dgeniLogLevel
 };
 
 var _excludePatterns = ['**/node_modules/**', '**/typings/**', '**/packages/**'];
@@ -625,7 +630,7 @@ gulp.task('_shred-devguide-examples', ['_shred-clean-devguide', '_copy-example-b
 });
 
 gulp.task('_shred-devguide-shared-jade', ['_shred-clean-devguide-shared-jade', '_copy-example-boilerplate'],  function() {
-  return docShredder.shred( _devguideShredJadeOptions);
+  return docShredder.shred(_devguideShredJadeOptions);
 });
 
 gulp.task('_shred-clean-devguide-shared-jade', function(cb) {
@@ -646,7 +651,7 @@ gulp.task('_shred-clean-devguide', function(cb) {
 
 gulp.task('_shred-api-examples', ['_shred-clean-api'], function() {
   checkAngularProjectPath();
-  return docShredder.shred( _apiShredOptions);
+  return docShredder.shred(_apiShredOptions);
 });
 
 gulp.task('_shred-clean-api', function(cb) {
@@ -1023,7 +1028,8 @@ function buildApiDocs(targetLanguage) {
   try {
     // Build a specialized package to generate different versions of the API docs
     var package = new Package('apiDocs', [require(path.resolve(TOOLS_PATH, 'api-builder/angular.io-package'))]);
-    package.config(function(targetEnvironments, writeFilesProcessor, readTypeScriptModules) {
+    package.config(function(log, targetEnvironments, writeFilesProcessor, readTypeScriptModules) {
+      log.level = _dgeniLogLevel;
       ALLOWED_LANGUAGES.forEach(function(target) { targetEnvironments.addAllowed(target); });
       if (targetLanguage) {
         targetEnvironments.activate(targetLanguage);
@@ -1058,7 +1064,8 @@ function buildShredMaps(shouldWrite) {
     fragmentsDir: _devguideShredOptions.fragmentsDir,
     jadeDir: './public/docs',
     outputDir: './public/docs',
-    writeFilesEnabled: shouldWrite
+    writeFilesEnabled: shouldWrite,
+    logLevel: _dgeniLogLevel
   };
   return docShredder.buildShredMap(options).then(function(docs) {
     return docs;

tools/api-builder/angular.io-package/index.js

@@ -155,8 +155,7 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe
   ]));
 })
 
-.config(function(filterUnwantedDecorators, log) {
-  log.level = 'info';
+.config(function(filterUnwantedDecorators) {
   filterUnwantedDecorators.decoratorsToIgnore = [
     'CONST',
     'IMPLEMENTS',

tools/api-builder/docs-package/index.js

@@ -20,11 +20,6 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage,
 .processor(require('./processors/addNotYetDocumentedProperty'))
 .processor(require('./processors/createDecoratorDocs'))
 
-// Configure the log service
-.config(function(log) {
-  log.level = 'info';
-})
-
 .config(function(parseTagsProcessor) {
   parseTagsProcessor.tagDefinitions.push({ name: 'internal', transforms: function() { return true; } });
   parseTagsProcessor.tagDefinitions.push({ name: 'syntax' });

tools/doc-shredder/doc-shredder.js

@@ -6,6 +6,8 @@ var _ = require('lodash');
 var globby = require('globby');
 var ignoreDirs = ['**/node_modules/**', '**/dist/**', '**/typings/**'];
 
+var _getLogLevel = function (options) { return options.logLevel || 'info'; }
+
 var shred = function(shredOptions) {
   try {
     var pkg;
@@ -14,7 +16,7 @@ var shred = function(shredOptions) {
     } else {
       pkg = createShredExamplePackage(shredOptions);
     }
-    var dgeni = new Dgeni([ pkg]);
+    var dgeni = new Dgeni([pkg]);
     return dgeni.generate();
   } catch(err) {
     console.log(err);
@@ -31,7 +33,8 @@ var shredSingleExampleDir = function(shredOptions, fileDir) {
   var options = {
     includeSubdirs: true,
     examplesDir: examplesDir,
-    fragmentsDir: fragmentsDir
+    fragmentsDir: fragmentsDir,
+    logLevel: _getLogLevel(shredOptions)
   }
   var cleanPath = path.join(fragmentsDir, '*.*')
   return del([ cleanPath, '!**/*.ovr.*']).then(function(paths) {
@@ -49,7 +52,8 @@ var shredSingleDir = function(shredOptions, filePath) {
   var options = {
     includeSubdirs: false,
     examplesDir: examplesDir,
-    fragmentsDir: fragmentsDir
+    fragmentsDir: fragmentsDir,
+    logLevel: _getLogLevel(shredOptions)
   }
   var cleanPath = path.join(fragmentsDir, '*.*')
   return del([ cleanPath, '!**/*.ovr.*']).then(function(paths) {
@@ -66,7 +70,8 @@ var shredSingleJadeDir = function(shredOptions, filePath) {
 
   var options = {
     includeSubdirs: false,
-    jadeDir: jadeDir
+    jadeDir: jadeDir,
+    logLevel: _getLogLevel(shredOptions)
   }
   // var cleanPath = path.join(jadeDir, '_.*.jade')
   //return delPromise([ cleanPath]).then(function(paths) {
@@ -105,12 +110,12 @@ function createShredExamplePackage(shredOptions) {
   initializePackage(pkg)
     .factory(require('./fileReaders/regionFileReader'))
     .processor(require('./processors/renderAsMarkdownProcessor'))
-
     .config(function(readFilesProcessor, regionFileReader) {
       readFilesProcessor.fileReaders = [regionFileReader];
     })
     // default configs - may be overridden
-    .config(function(readFilesProcessor) {
+    .config(function(log, readFilesProcessor) {
+      log.level = _getLogLevel(shredOptions);
       // Specify the base path used when resolving relative paths to source and output files
       readFilesProcessor.basePath = "/";
 
@@ -128,7 +133,7 @@ function createShredExamplePackage(shredOptions) {
       // this just uses globby to 'preglob' the include files ( and  exclude the node_modules).
       var includeFiles = globby.sync( includeFiles, { ignore: ignoreDirs } );
 
-      console.log(`Shredding ${includeFiles.length} files inside ${shredOptions.examplesDir}`);
+      log.info(`Shredding ${includeFiles.length} files inside ${shredOptions.examplesDir}`);
 
       readFilesProcessor.sourceFiles = [ {
         // Process all candidate files in `src` and its subfolders ...
@@ -159,7 +164,8 @@ function createShredJadePackage(shredOptions) {
     .factory(require('./fileReaders/regionFileReader'))
     .processor(require('./processors/renderAsJadeProcessor'))
 
-    .config(function(readFilesProcessor, regionFileReader) {
+    .config(function(log, readFilesProcessor, regionFileReader) {
+      log.level = _getLogLevel(shredOptions);
       readFilesProcessor.fileReaders = [regionFileReader];
     })
     // default configs - may be overridden
@@ -211,7 +217,8 @@ var createShredMapPackage = function(mapOptions) {
     .config(function(shredMapProcessor) {
       shredMapProcessor.options = options;
     })
-    .config(function(readFilesProcessor, extractPathsReader ) {
+    .config(function(log, readFilesProcessor, extractPathsReader ) {
+      log.level = _getLogLevel(mapOptions);
       readFilesProcessor.fileReaders = [ extractPathsReader];
     })
     // default configs - may be overridden
@@ -281,8 +288,6 @@ var createShredMapPackage = function(mapOptions) {
       //});
     });
 
-
-
   return pkg;
 }
 
@@ -334,8 +339,4 @@ function initializePackage(pkg) {
     .processor({ name: 'docs-rendered', $runAfter: ['rendering-docs'] })
     .processor({ name: 'writing-files', $runAfter: ['docs-rendered'] })
     .processor({ name: 'files-written', $runAfter: ['writing-files'] })
-    .config(function(log) {
-      // Set logging level
-      log.level = 'info';
-    })
 }