docs(tooling): new mixin for sharing jade files

merges #725

gulpfile.js

@@ -49,6 +49,11 @@ var _devguideShredOptions =  {
   zipDir: path.join(RESOURCES_PATH, 'zips')
 };
 
+var _devguideShredJadeOptions =  {
+  jadeDir: DOCS_PATH
+
+};
+
 var _apiShredOptions =  {
   examplesDir: path.join(ANGULAR_PROJECT_PATH, 'modules/angular2/examples'),
   fragmentsDir: path.join(DOCS_PATH, '_fragments/_api'),
@@ -260,15 +265,20 @@ gulp.task('remove-example-boilerplate', function() {
 });
 
 gulp.task('serve-and-sync', ['build-docs'], function (cb) {
-  watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
+  // watchAndSync({devGuide: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
+  watchAndSync({devGuide: true, devGuideJade: true, apiDocs: true, apiExamples: true, localFiles: true}, cb);
 });
 
 gulp.task('serve-and-sync-api', ['build-docs'], function (cb) {
   watchAndSync({apiDocs: true, apiExamples: true}, cb);
 });
 
-gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers', '_zip-examples'], function (cb) {
-  watchAndSync({devGuide: true, localFiles: true}, cb);
+gulp.task('serve-and-sync-devguide', ['build-devguide-docs', 'build-plunkers' ], function (cb) {
+  watchAndSync({devGuide: true, devGuideJade: true, localFiles: true}, cb);
+});
+
+gulp.task('_serve-and-sync-jade', function (cb) {
+  watchAndSync({devGuideJade: true, localFiles: true}, cb);
 });
 
 gulp.task('build-and-serve', ['build-docs'], function (cb) {
@@ -279,7 +289,7 @@ gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunker
 
 gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs', 'build-dart-cheatsheet']);
 
-gulp.task('build-devguide-docs', ['_shred-devguide-examples'], function() {
+gulp.task('build-devguide-docs', ['_shred-devguide-examples', '_shred-devguide-shared-jade'], function() {
   return buildShredMaps(true);
 });
 
@@ -384,6 +394,15 @@ gulp.task('_shred-devguide-examples', ['_shred-clean-devguide'], function() {
   return docShredder.shred( _devguideShredOptions);
 });
 
+gulp.task('_shred-devguide-shared-jade', ['_shred-clean-devguide-shared-jade'],  function() {
+  return docShredder.shred( _devguideShredJadeOptions);
+});
+
+gulp.task('_shred-clean-devguide-shared-jade', function(cb) {
+  var cleanPath = path.join(DOCS_PATH, '**/_.*.jade')
+  return delPromise([ cleanPath]);
+});
+
 gulp.task('_shred-clean-devguide', function(cb) {
   var cleanPath = path.join(_devguideShredOptions.fragmentsDir, '**/*.*')
   return delPromise([ cleanPath, '!**/*.ovr.*', '!**/_api/**']);
@@ -523,6 +542,9 @@ function watchAndSync(options, cb) {
   if (options.devGuide) {
     devGuideExamplesWatch(_devguideShredOptions, browserSync.reload);
   }
+  if (options.devGuideJade) {
+    devGuideSharedJadeWatch( { jadeDir: DOCS_PATH}, browserSync.reload);
+  }
   if (options.apiDocs) {
     apiSourceWatch(browserSync.reload);
   }
@@ -603,6 +625,20 @@ function devGuideExamplesWatch(shredOptions, postShredAction) {
   });
 }
 
+function devGuideSharedJadeWatch(shredOptions, postShredAction) {
+  var includePattern = path.join(DOCS_PATH, '**/*.jade');
+  var excludePattern = '!' + path.join(shredOptions.jadeDir, '**/node_modules/**/*.*');
+  // removed this version because gulp.watch has the same glob issue that dgeni has.
+  // gulp.watch([includePattern, excludePattern], {readDelay: 500}, function (event, done) {
+  var files = globby.sync( [includePattern], { ignore: [ '**/node_modules/**']});
+  gulp.watch([files], {readDelay: 500}, function (event, done) {
+    gutil.log('Dev Guide jade file changed')
+    gutil.log('Event type: ' + event.type); // added, changed, or deleted
+    gutil.log('Event path: ' + event.path); // The path of the modified file
+    return docShredder.shredSingleJadeDir(shredOptions, event.path).then(postShredAction);
+  });
+}
+
 
 // Generate the API docs for the specified language, if not specified then it defaults to ts
 function buildApiDocs(targetLanguage) {

public/_includes/_util-fns.jade

@@ -1,5 +1,9 @@
 //- Mixins and associated functions
 
+mixin includeShared(filePath, region)
+  - var newPath = translatePath(filePath, region);
+  !=partial(newPath)
+
 mixin makeExample(filePath, region, title, stylePatterns)
   - var language = attributes.language || getExtn(filePath);
   - var frag = getFrag(filePath, region);
@@ -44,6 +48,27 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
 
 
 //---------------------------------------------------------------------------------------------------------
+- var translatePath = function(filePath, region) {
+-   filePath = filePath.trim();
+-   var regionPad = (region && region.length) ? '-' + region.toString() : '';
+-   var matches = /{(.*)}.*/.exec(filePath);
+-   if (matches) {
+-     var topLevelDir = matches[1];
+-     var currentPath = current.path;
+-     var subPaths = currentPath.slice(2);
+-     subPaths[subPaths.length - 1] = "_." + subPaths[subPaths.length - 1];
+-     var newPath = getPathToDocs() + topLevelDir + '/' + subPaths.join("/");
+-     var result = newPath + regionPad + ".jade";
+-   } else {
+-     var extn = getExtn(filePath);
+-     var baseFileName = getBaseFileName(filePath);
+-     var noExtnFileName = baseFileName.substr(0,baseFileName.length - (extn.length + 1));
+-     var folder = getFolder(filePath);
+-     var result = folder + "/_." + noExtnFileName + regionPad + "." + extn;
+-   }
+-   return result
+- }
+
 
 - var EMPTY_STRINGS = [ '','','','','','',''];
 
@@ -146,6 +171,16 @@ mixin makeJson( filePath, jsonConfig, title, stylePatterns)
 -   return ix > 0 ? fileName.substr(ix+1) : "";
 - }
 
+- var getBaseFileName = function(fileName) {
+-   var ix = fileName.lastIndexOf('/');
+-   return ix > 0 ? fileName.substr(ix+1) : "";
+- }
+
+- var getFolder = function(fileName) {
+-   var ix = fileName.lastIndexOf('/');
+-   return ix > 0 ? fileName.substr(0, ix) : "";
+- }
+
 - var getPathToDocs = function() {
 -   // simple way to only take as many '../' sections as we need to back up to the 'docs' dir
 -   // from the current document

tools/doc-shredder/doc-shredder.js

@@ -10,7 +10,12 @@ var globby = require('globby');
 
 var shred = function(shredOptions) {
   try {
-    var pkg = createShredPackage(shredOptions);
+    var pkg;
+    if (shredOptions.jadeDir) {
+      pkg = createShredJadePackage(shredOptions);
+    } else {
+      pkg = createShredExamplePackage(shredOptions);
+    }
     var dgeni = new Dgeni([ pkg]);
     return dgeni.generate();
   } catch(err) {
@@ -38,6 +43,23 @@ var shredSingleDir = function(shredOptions, filePath) {
   });
 }
 
+var shredSingleJadeDir = function(shredOptions, filePath) {
+  shredOptions = resolveShredOptions(shredOptions);
+  var fileDir = path.dirname(filePath);
+  var relativePath = path.relative(shredOptions.jadeDir, fileDir);
+  var jadeDir = path.join(shredOptions.jadeDir, relativePath);
+
+  var options = {
+    includeSubdirs: false,
+    jadeDir: jadeDir
+  }
+  var cleanPath = path.join(jadeDir, '_.*.jade')
+  return delPromise([ cleanPath]).then(function(paths) {
+    console.log('Deleted files/folders:\n', paths.join('\n'));
+    return shred(options);
+  });
+}
+
 var buildShredMap = function(shredMapOptions) {
   try {
     var pkg = createShredMapPackage(shredMapOptions);
@@ -53,10 +75,11 @@ var buildShredMap = function(shredMapOptions) {
 module.exports = {
   shred: shred,
   shredSingleDir: shredSingleDir,
+  shredSingleJadeDir: shredSingleJadeDir,
   buildShredMap: buildShredMap
 };
 
-function createShredPackage(shredOptions) {
+function createShredExamplePackage(shredOptions) {
   var pkg = new Dgeni.Package('doc-shredder', [
     // require('dgeni-packages/base') - doesn't work
   ]);
@@ -105,6 +128,59 @@ function createShredPackage(shredOptions) {
   return pkg;
 }
 
+function createShredJadePackage(shredOptions) {
+  var pkg = new Dgeni.Package('jade-doc-shredder', [
+    // require('dgeni-packages/base') - doesn't work
+  ]);
+
+  var options = shredOptions;
+  options.jadeDir = path.resolve(options.jadeDir);
+  options.includeSubdirs = options.includeSubdirs == null ? true : options.includeSubdirs;
+
+  initializePackage(pkg)
+    .factory(require('./fileReaders/regionFileReader'))
+    .processor(require('./processors/renderAsJadeProcessor'))
+
+    .config(function(readFilesProcessor, regionFileReader) {
+      readFilesProcessor.fileReaders = [regionFileReader];
+    })
+    // default configs - may be overridden
+    .config(function(readFilesProcessor) {
+      // Specify the base path used when resolving relative paths to source and output files
+      readFilesProcessor.basePath = "/";
+
+      // Specify collections of source files that should contain the documentation to extract
+      var extns = ['*.jade' ];
+      var includeFiles = extns.map(function(extn) {
+        if (options.includeSubdirs) {
+          return path.join(options.jadeDir, '**', extn);
+        } else {
+          return path.join(options.jadeDir, extn);
+        }
+      });
+
+      // HACK ( next two lines) because the glob function that dgeni uses internally isn't good at removing 'node_modules' early
+      // this just uses globby to 'preglob' the include files ( and  exclude the node_modules).
+      var nmPattern = '**/node_modules/**';
+      var includeFiles = globby.sync( includeFiles, { ignore: [nmPattern] } );
+
+      readFilesProcessor.sourceFiles = [ {
+        // Process all candidate files in `src` and its subfolders ...
+        include: includeFiles ,
+        exclude: [ '**/node_modules/**', '**/typings/**', '**/packages/**', '**/build/**', '**/_code-examples.jade'],
+        // When calculating the relative path to these files use this as the base path.
+        // So `src/foo/bar.js` will have relative path of `foo/bar.js`
+        basePath: options.jadeDir
+      } ];
+    })
+    .config(function(writeFilesProcessor) {
+      // Specify where the writeFilesProcessor will write our generated doc files
+      writeFilesProcessor.outputFolder  = '.';
+    });
+  return pkg;
+}
+
+
 var createShredMapPackage = function(mapOptions) {
   var pkg = new Dgeni.Package('doc-shred-mapper', [
     require('dgeni-packages/base'),

tools/doc-shredder/processors/renderAsJadeProcessor.js

@@ -0,0 +1,24 @@
+var path = require('canonical-path');
+/**
+ * dgProcessor
+ * @description
+ *
+ */
+module.exports = function renderAsJadeProcessor() {
+  return {
+    $runAfter: ['readFilesProcessor'],
+    $runBefore: ['writing-files'],
+    $process: function(docs) {
+      return docs.map(function(doc) {
+        var fileInfo = doc.fileInfo;
+        doc.renderedContent =  doc.content ;
+        var regionSuffix =  (doc.regionName && doc.regionName.length) ? "-" + doc.regionName.trim() : "";
+        var origName = fileInfo.baseName + "." + fileInfo.extension;
+
+        var newName = "_." + fileInfo.baseName + regionSuffix +  "." + fileInfo.extension;
+        doc.outputPath = fileInfo.filePath.replace(origName, newName);
+        return doc;
+      })
+    }
+  };
+};

tools/doc-shredder/regionExtractor.js

@@ -180,6 +180,12 @@ function getCommentInfo(extension) {
         plasterPattern: '# {tag} '
       };
       break;
+    case 'jade':
+      commentInfo = {
+        prefix: '//',
+        plasterPattern: '// {tag} '
+      };
+      break;
     default:
       return null;
   }