shred and watch build tooling ( dgeni, gulp, jade)

Author: jtraband

README.md

@@ -12,6 +12,25 @@ Angular.io is currently the preview site for Angular 2. This site also includes
 3. run `harp server`
 4. Open this url in the browser: [http://localhost:9000/](http://localhost:9000/)
 
+## Development setup with watches
+ 1. cd into root directory `angular.io/`
+ 2. run `gulp serve-and-watch`
+ 3. Open this url in the browser: [http://localhost:9000/](http://localhost:9000/)
+ 4. Refresh your browser to see any changes.
+
+## Development setup with watches and browser reload
+ 1. cd into root directory `angular.io/`
+ 2. install `browser-sync`
+
+    `npm install -g browser-sync`<br/>
+
+       *or on Windows*<br/>
+
+    `npm install -g browser-sync --msvs_version=2013`
+
+ 3. run `gulp serve-and-watch`
+ 4. run `browser-sync start --proxy localhost:9000 --files "public/docs/**/*/**/*" --reloadDelay 500`
+ 5. browser will launch and stay refreshed automatically.
 
 ## Technology Used
 - Angular 1.x: The production ready version of Angular

gulpfile.js

@@ -0,0 +1,76 @@
+var gulp = require('gulp');
+var watch = require('gulp-watch');
+var gutil = require('gulp-util');
+var Dgeni = require('dgeni');
+var path = require('path');
+var del = require('del');
+
+var docShredder = require('./public/doc-shredder/doc-shredder');
+
+var shredOptions =  {
+  basePath: path.resolve('./public/docs'),
+  sourceDir: "_examples",
+  destDir:  "_fragments"
+};
+
+gulp.task('shred-full', ['shred-clean'], function() {
+  docShredder.shred( shredOptions);
+});
+
+gulp.task('serve-and-watch', function (cb) {
+  var pattern = path.join(shredOptions.basePath, shredOptions.sourceDir, "**/*.*");
+
+  execCommands(['harp server'])
+
+  watch([ pattern], function(event, done) {
+    console.log('Event type: ' + event.event); // added, changed, or deleted
+    console.log('Event path: ' + event.path); // The path of the modified file
+    docShredder.shredSingleDir(shredOptions, event.path);
+  });
+
+});
+
+gulp.task('shred-clean', function(cb) {
+  var cleanPath = path.join(shredOptions.basePath, shredOptions.destDir, '**/*.*')
+  del([ cleanPath, '!**/*.ovr.*'], function (err, paths) {
+    // console.log('Deleted files/folders:\n', paths.join('\n'));
+    cb();
+  });
+});
+
+
+// added options are: shouldLog
+// cb is function(err, stdout, stderr);
+function execCommands(cmds, options, cb) {
+  options = options || {};
+  options.shouldThrow = options.shouldThrow == null ? true : options.shouldThrow;
+  options.shouldLog = options.shouldLog == null ? true : options.shouldLog;
+  if (!cmds || cmds.length == 0) cb(null, null, null);
+  var exec = require('child_process').exec;  // just to make it more portable.
+  exec(cmds[0], options, function(err, stdout, stderr) {
+    if (err == null) {
+      if (options.shouldLog) {
+        gutil.log('cmd: ' + cmds[0]);
+        gutil.log('stdout: ' + stdout);
+      }
+      if (cmds.length == 1) {
+        cb(err, stdout, stderr);
+      } else {
+        execCommands(cmds.slice(1), options, cb);
+      }
+    } else {
+      if (options.shouldLog) {
+        gutil.log('exec error on cmd: ' + cmds[0]);
+        gutil.log('exec error: ' + err);
+        if (stdout) gutil.log('stdout: ' + stdout);
+        if (stderr) gutil.log('stderr: ' + stderr);
+      }
+      if (err && options.shouldThrow) throw err;
+      cb(err, stdout, stderr);
+    }
+  });
+}
+
+
+
+gulp.task('default', ['shred']);

package.json

@@ -0,0 +1,36 @@
+{
+  "name": "angular.io",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Angular 2 documentation",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git"
+  },
+  "licenses": [
+    {
+      "type": "Apache",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  ],
+  "bugs": {
+    "url": ""
+  },
+  "devDependencies": {
+    "canonical-path": "0.0.2",
+    "del": "^1.2.0",
+    "dgeni": "^0.4.0",
+    "dgeni-packages": "^0.10.0",
+    "gulp": "^3.5.6",
+    "gulp-util": "^3.0.6",
+    "gulp-watch": "^4.3.4",
+    "lodash": "^3.10.1",
+    "path": "^0.11.14"
+  },
+  "contributors": [
+    "Jay Traband <[email protected]>"
+  ]
+}

public/_includes/_util-fns.jade

@@ -0,0 +1,35 @@
+- var getFrag = function(fileName) {
+-   var frag = partial(fileName);
+-   if (frag == null) {
+-     return "BAD FILENAME: " + fileName + "   Current path: " + current.path;
+-   } else {
+-     // ``` gets translated to <pre><code>.....</code></pre> and we need
+-     // to remove this from the fragment prefix is 11 long and suffix is 13 long
+-     var r = frag.substring(11, frag.length-13);
+-     return r;
+-   }
+- }
+
+- var getExtn = function(fileName) {
+-   var ix = fileName.lastIndexOf('.');
+-   return ix > 0 ? fileName.substr(ix+1) : "";
+- }
+
+// HACK: to avoid having to include a path in makeTabs calls
+- var currentPath = current.path;
+// need to back up to 'docs'
+- var pathToFrags = "../../../../../../../../../../../".substr(0, (currentPath.length-2)*3) + "_fragments/";
+
+mixin makeTabs(path, fileNames, tabNames)
+  - fileNames = fileNames.split(",");
+  - tabNames = tabNames.split(",")
+  // .p Length #{currentPath.length}
+  code-tabs
+      each fileName,index in fileNames
+        - var tabName = tabNames[index].trim();
+        - var fileName = fileNames[index].trim();
+        - var extn = getExtn(fileName);
+        // - var extPath = pathToFrags + (path.length ? path + "/" : "");
+        - var extPath = pathToFrags + path + "/";
+        code-pane(language="#{extn}" name="#{tabName}" format="linenums")
+            != getFrag(extPath + fileName + ".md")

public/doc-shredder/doc-shredder.js

@@ -0,0 +1,136 @@
+
+// Canonical path provides a consistent path (i.e. always forward slashes) across different OSes
+var path = require('canonical-path');
+// var path = require('path');
+var del = require('del');
+var Dgeni = require('dgeni');
+var _ = require('lodash');
+
+var createPackage = function(shredOptions) {
+  var shredder = new Dgeni.Package('doc-shredder', [
+    // require('dgeni-packages/base') - doesn't work
+  ]);
+  shredder.options = resolveOptions(shredOptions);
+  return configure(shredder);
+};
+
+var resolveOptions = function(shredOptions) {
+  return _.defaults({}, shredOptions, {
+    basePath: path.resolve('.'),
+    // read files from any subdir under here
+    sourceDir: "docs/_examples",
+    // shredded files get copied here with same subdir structure.
+    destDir: "docs/_fragments",
+    // whether to include subdirectories when shredding.
+    includeSubdirs: true
+  });
+}
+
+var shred = function(shredOptions) {
+  try {
+    var pkg = createPackage(shredOptions);
+    var dgeni = new Dgeni([ pkg]);
+    return dgeni.generate();
+  } catch(x) {
+    console.log(x.stack);
+    throw x;
+  }
+}
+
+var shredSingleDir = function(shredOptions, filePath) {
+  shredOptions = resolveOptions(shredOptions);
+  var root = path.resolve(shredOptions.basePath, shredOptions.sourceDir);
+  var fileDir = path.dirname(filePath);
+  var relativePath = path.relative(root, fileDir);
+  var sourceDir = path.join(shredOptions.sourceDir, relativePath);
+  var destDir = path.join(shredOptions.destDir, relativePath);
+  var options = {
+    basePath: shredOptions.basePath,
+    includeSubdirs: false,
+    sourceDir: sourceDir,
+    destDir:  destDir
+  }
+  var cleanPath = path.join(shredOptions.basePath, destDir, '*.*')
+  del([ cleanPath, '!**/*.ovr.*'], function (err, paths) {
+    // console.log('Deleted files/folders:\n', paths.join('\n'));
+    return shred(options);
+  });
+
+}
+
+module.exports = {
+  shred: shred,
+  shredSingleDir: shredSingleDir,
+  createPackage: createPackage,
+  resolveOptions: resolveOptions
+};
+
+function configure(shredder) {
+  var options = shredder.options;
+  shredder
+    .processor(require('dgeni-packages/base/processors/read-files'))
+    .processor(require('dgeni-packages/base/processors/write-files'))
+    .factory(require('dgeni-packages/base/services/writefile'))
+
+    // Ugh... Boilerplate that dgeni needs to sequence operations
+    .processor({ name: 'reading-files' })
+    .processor({ name: 'files-read', $runAfter: ['reading-files'] })
+    .processor({ name: 'processing-docs', $runAfter: ['files-read'] })
+    .processor({ name: 'docs-processed', $runAfter: ['processing-docs'] })
+    .processor({ name: 'adding-extra-docs', $runAfter: ['docs-processed'] })
+    .processor({ name: 'extra-docs-added', $runAfter: ['adding-extra-docs'] })
+    .processor({ name: 'computing-ids', $runAfter: ['extra-docs-added'] })
+    .processor({ name: 'ids-computed', $runAfter: ['computing-ids'] })
+    .processor({ name: 'computing-paths', $runAfter: ['ids-computed'] })
+    .processor({ name: 'paths-computed', $runAfter: ['computing-paths'] })
+    .processor({ name: 'rendering-docs', $runAfter: ['paths-computed'] })
+    .processor({ name: 'docs-rendered', $runAfter: ['rendering-docs'] })
+    .processor({ name: 'writing-files', $runAfter: ['docs-rendered'] })
+    .processor({ name: 'files-written', $runAfter: ['writing-files'] })
+
+    .factory(require('./fileShredder'))
+    .factory(require('./regionExtractor'))
+    .processor(require('./mdWrapperProcessor'))
+
+    .config(function(log) {
+      // Set logging level
+      log.level = 'info';
+    })
+
+
+    .config(function(readFilesProcessor, fileShredder ) {
+      readFilesProcessor.fileReaders = [ fileShredder];
+    })
+
+    // default configs - may be overriden
+    .config(function(readFilesProcessor) {
+
+      // Specify the base path used when resolving relative paths to source and output files
+      readFilesProcessor.basePath = options.basePath;
+
+      // Specify collections of source files that should contain the documentation to extract
+      var extns = ['*.js', '*.html', '*.ts', '*.css' ];
+      var includeFiles = extns.map(function(extn) {
+        if (options.includeSubdirs) {
+          return path.join(options.sourceDir, '**', extn);
+        } else {
+          return path.join(options.sourceDir, extn);
+        }
+      });
+      readFilesProcessor.sourceFiles = [
+        {
+          // Process all candidate files in `src` and its subfolders ...
+          include: includeFiles,
+
+          // 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.sourceDir
+        }
+      ];
+    })
+    .config(function(writeFilesProcessor) {
+      // Specify where the writeFilesProcessor will write our generated doc files
+      writeFilesProcessor.outputFolder  = options.destDir;
+    });
+  return shredder;
+}

public/doc-shredder/fileShredder.js

@@ -0,0 +1,30 @@
+/**
+ * @dgService htmlFileShredder
+ * @description
+ */
+module.exports = function fileShredder(log, regionExtractor) {
+  return {
+    name: 'fileShredder',
+
+    getDocs: function (fileInfo) {
+      var commentMarkers;
+      switch (fileInfo.extension) {
+        case 'ts':
+        case 'js':
+          commentMarkers = ['//'];
+          break;
+        case 'html':
+          commentMarkers = ['<!--'];
+          break;
+        case 'css':
+          commentMarkers = ['/*'];
+          break;
+        default:
+          return [];
+      }
+      log.info("fileShredder processing: " + fileInfo.projectRelativePath);
+      return regionExtractor(fileInfo.content, commentMarkers);
+    }
+  }
+}
+

public/doc-shredder/mdWrapperProcessor.js

@@ -0,0 +1,26 @@
+// Not currently used - but wanted to leave it as an example
+// var _ = require('lodash');
+
+/**
+ * dgProcessor shredderProcessor
+ * @description
+ *
+ */
+module.exports = function mdWrapperProcessor(log) {
+  return {
+    $runAfter: ['readFilesProcessor'],
+    $runBefore: ['writing-files'],
+    $process: function(docs) {
+      return docs.map(function(doc) {
+        var fileInfo = doc.fileInfo;
+        doc.renderedContent =  '```\n' + doc.content + '\n```';
+        var regionSuffix =  (doc.regionName && doc.regionName.length) ? "-" + doc.regionName.trim() : "";
+        var origName = fileInfo.baseName + "." + fileInfo.extension;
+
+        var newName = fileInfo.baseName + regionSuffix +  "." + fileInfo.extension + ".md";
+        doc.outputPath = fileInfo.relativePath.replace(origName, newName);
+        return doc;
+      })
+    }
+  };
+};