chore(docs): use symlinks to build docs

so that we can just edit source files without rebuilding docs.

this works for all docs files, except for those that are generated
or rewritten during build.

docs/src/gen-docs.js

@@ -12,8 +12,10 @@ process.on('uncaughtException', function(err) {
 var start = now();
 var docs;
 
-writer.makeDir('build/docs/syntaxhighlighter').then(function() {
+writer.makeDir('build/docs/', true).then(function() {
-  console.log('Generating Angular Reference Documentation...');
+  return writer.makeDir('build/docs/partials/');
+}).then(function() {
+  console.log('Generating AngularJS Reference Documentation...');
   return reader.collect();
 }).then(function generateHtmlDocPartials(docs_) {
   docs = docs_;
@@ -41,8 +43,10 @@ writer.makeDir('build/docs/syntaxhighlighter').then(function() {
 function writeTheRest(writesFuture) {
   var metadata = ngdoc.metadata(docs);
 
-  writesFuture.push(writer.copyDir('img'));
+  writesFuture.push(writer.symlinkTemplate('css'));
-  writesFuture.push(writer.copyDir('font'));
+  writesFuture.push(writer.symlinkTemplate('font'));
+  writesFuture.push(writer.symlinkTemplate('img'));
+  writesFuture.push(writer.symlinkTemplate('js'));
 
   var manifest = 'manifest="/build/docs/appcache.manifest"';
 
@@ -66,38 +70,27 @@ function writeTheRest(writesFuture) {
   writesFuture.push(writer.copy('docs/src/templates/index.html', 'index-jq-debug.html',
                                 writer.replace, {'doc:manifest': ''}));
 
-  writesFuture.push(writer.copyTpl('offline.html'));
+  writesFuture.push(writer.symlinkTemplate('offline.html'));
-  writesFuture.push(writer.copyTpl('docs-scenario.html'));
-  writesFuture.push(writer.copyTpl('js/jquery.min.js'));
-  writesFuture.push(writer.copyTpl('js/jquery.js'));
 
-  writesFuture.push(writer.output('js/docs-keywords.js',
+  writesFuture.push(writer.copyTemplate('docs-scenario.html')); // will be rewritten, don't symlink
+  writesFuture.push(writer.output('docs-scenario.js', ngdoc.scenarios(docs)));
+
+  writesFuture.push(writer.output('docs-keywords.js',
                                 ['NG_PAGES=', JSON.stringify(metadata).replace(/{/g, '\n{'), ';']));
   writesFuture.push(writer.output('sitemap.xml', new SiteMap(docs).render()));
-  writesFuture.push(writer.output('docs-scenario.js', ngdoc.scenarios(docs)));
+
   writesFuture.push(writer.output('robots.txt', 'Sitemap: http://docs.angularjs.org/sitemap.xml\n'));
   writesFuture.push(writer.output('appcache.manifest',appCache()));
-  writesFuture.push(writer.copyTpl('.htaccess'));
+  writesFuture.push(writer.copyTemplate('.htaccess')); // will be rewritten, don't symlink
 
-  writesFuture.push(writer.copy('docs/src/templates/js/docs.js', 'js/docs.js'));
+  writesFuture.push(writer.symlinkTemplate('app.yaml'));
-
+  writesFuture.push(writer.symlinkTemplate('index.yaml'));
-  writesFuture.push(writer.copy('docs/src/templates/css/bootstrap.min.css', 'css/bootstrap.min.css'));
+  writesFuture.push(writer.symlinkTemplate('favicon.ico'));
-  writesFuture.push(writer.copy('docs/src/templates/css/docs.css', 'css/docs.css'));
+  writesFuture.push(writer.symlinkTemplate('main.py'));
-  writesFuture.push(writer.copy('docs/src/templates/css/font-awesome.css', 'css/font-awesome.css'));
-
-  writesFuture.push(writer.copyTpl('font/fontawesome-webfont.eot'));
-  writesFuture.push(writer.copyTpl('font/fontawesome-webfont.svg'));
-  writesFuture.push(writer.copyTpl('font/fontawesome-webfont.svgz'));
-  writesFuture.push(writer.copyTpl('font/fontawesome-webfont.ttf'));
-  writesFuture.push(writer.copyTpl('font/fontawesome-webfont.woff'));
-
-  writesFuture.push(writer.copyTpl('app.yaml'));
-  writesFuture.push(writer.copyTpl('index.yaml'));
-  writesFuture.push(writer.copyTpl('favicon.ico'));
-  writesFuture.push(writer.copyTpl('main.py'));
 }
 
 
 function now() { return new Date().getTime(); }
 
 function noop() {};
+

docs/src/templates/index.html

@@ -42,7 +42,7 @@
       addTag('script', {src: path('angular-bootstrap.js') }, sync);
       addTag('script', {src: path('angular-bootstrap-prettify.js') }, sync);
       addTag('script', {src: 'js/docs.js'}, sync);
-      addTag('script', {src: 'js/docs-keywords.js'}, sync);
+      addTag('script', {src: 'docs-keywords.js'}, sync);
 
       function path(name) {
         if (gae) {

docs/src/writer.js

@@ -4,7 +4,7 @@
  */
 var qfs = require('q-fs');
 var Q = require('qq');
-var OUTPUT_DIR = "build/docs/";
+var OUTPUT_DIR = 'build/docs/';
 var fs = require('fs');
 
 exports.output = output;
@@ -17,29 +17,27 @@ function output(file, content) {
 };
 
 //recursively create directory
-exports.makeDir = function(path) {
+exports.makeDir = function(p) {
-  var parts = path.split(/\//);
+  var parts = p.split(/\//);
   var path = ".";
-  //Sequentially create directories
-  var done = Q.defer();
-  (function createPart() {
 
-    if(!parts.length) {
+  // Recursively rebuild directory structure
-      done.resolve();
+  return qfs.exists(p).
-    } else {
+      then(function createPart(exists) {
-      path += "/" + parts.shift();
+        if(!exists && parts.length) {
-      qfs.isDirectory(path).then(function(isDir) {
+          path += "/" + parts.shift();
-        if(!isDir) {
+          return qfs.exists(path).then(function(exists) {
-          qfs.makeDirectory(path);
+            if (!exists) {
+              return qfs.makeDirectory(path).then(createPart, createPart);
+            } else {
+              return createPart();
+            }
+          });
         }
-        createPart();
       });
-    }
-  })();
-  return done.promise;
 };
 
-exports.copyTpl = function(filename) {
+exports.copyTemplate = function(filename) {
   return exports.copy('docs/src/templates/' + filename, filename);
 };
 
@@ -59,8 +57,23 @@ exports.copy = function(from, to, transform) {
     }
     return output(to, content);
   });
+};
+
+
+exports.symlinkTemplate= symlinkTemplate;
+function symlinkTemplate(filename) {
+  var dest = OUTPUT_DIR + filename,
+      dirDepth = dest.split('/').length,
+      src = Array(dirDepth).join('../') + 'docs/src/templates/' + filename;
+
+  return qfs.exists(dest).then(function(exists) {
+    if (!exists) {
+      qfs.symbolicLink(dest, src);
+    }
+  });
 }
 
+
 /* Replace placeholders in content accordingly
  * @param content{string} content to be modified
  * @param replacements{obj} key and value pairs in which key will be replaced with value in content
@@ -132,3 +145,4 @@ exports.toString = function toString(obj) {
 
 
 function noop() {};
+