doc: update style for iojs

* updates the styling for the iojs docs
* pulls the processing step for markdown files into
  a separate module
* adds the ability to insert comments into the markdown

PR-URL: https://github.com/iojs/io.js/pull/297
Fixes: https://github.com/iojs/iojs.github.io/issues/23
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

3 files changed, 116 insertions, 43 deletions

diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index 2bab2f3ef3..768f3b32e1 100755
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -20,6 +20,7 @@
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+var processIncludes = require('./preprocess.js');
 var marked = require('marked');
 var fs = require('fs');
 var path = require('path');
@@ -52,48 +53,10 @@ console.error('Input file = %s', inputFile);
 fs.readFile(inputFile, 'utf8', function(er, input) {
   if (er) throw er;
   // process the input for @include lines
-  processIncludes(input, next);
+  processIncludes(inputFile, input, next);
 });
 
 
-var includeExpr = /^@include\s+([A-Za-z0-9-_]+)(?:\.)?([a-zA-Z]*)$/gmi;
-var includeData = {};
-function processIncludes(input, cb) {
-  var includes = input.match(includeExpr);
-  if (includes === null) return cb(null, input);
-  var errState = null;
-  console.error(includes);
-  var incCount = includes.length;
-  if (incCount === 0) cb(null, input);
-  includes.forEach(function(include) {
-    var fname = include.replace(/^@include\s+/, '');
-    if (!fname.match(/\.markdown$/)) fname += '.markdown';
-
-    if (includeData.hasOwnProperty(fname)) {
-      input = input.split(include).join(includeData[fname]);
-      incCount--;
-      if (incCount === 0) {
-        return cb(null, input);
-      }
-    }
-
-    var fullFname = path.resolve(path.dirname(inputFile), fname);
-    fs.readFile(fullFname, 'utf8', function(er, inc) {
-      if (errState) return;
-      if (er) return cb(errState = er);
-      processIncludes(inc, function(er, inc) {
-        if (errState) return;
-        if (er) return cb(errState = er);
-        incCount--;
-        includeData[fname] = inc;
-        input = input.split(include+'\n').join(includeData[fname]+'\n');
-        if (incCount === 0) {
-          return cb(null, input);
-        }
-      });
-    });
-  });
-}
 
 
 function next(er, input) {
diff --git a/tools/doc/html.js b/tools/doc/html.js
index 088eb4490d..dd9efcb9ae 100644
--- a/tools/doc/html.js
+++ b/tools/doc/html.js
@@ -22,17 +22,63 @@
 var fs = require('fs');
 var marked = require('marked');
 var path = require('path');
+var preprocess = require('./preprocess.js');
 
 module.exports = toHTML;
 
+// TODO(chrisdickinson): never stop vomitting / fix this.
+var gtocPath = path.resolve(path.join(__dirname, '..', '..', 'doc', 'api', '_toc.markdown'));
+var gtocLoading = null;
+var gtocData = null;
+
 function toHTML(input, filename, template, cb) {
-  var lexed = marked.lexer(input);
-  fs.readFile(template, 'utf8', function(er, template) {
-    if (er) return cb(er);
-    render(lexed, filename, template, cb);
+  if (gtocData) {
+    return onGtocLoaded();
+  }
+
+  if (gtocLoading === null) {
+    gtocLoading = [onGtocLoaded];
+    return loadGtoc(function(err, data) {
+      if (err) throw err;
+      gtocData = data;
+      gtocLoading.forEach(function(xs) {
+        xs();
+      });
+    });
+  }
+
+  if (gtocLoading) {
+    return gtocLoading.push(onGtocLoaded);
+  }
+
+  function onGtocLoaded() {
+    var lexed = marked.lexer(input);
+    fs.readFile(template, 'utf8', function(er, template) {
+      if (er) return cb(er);
+      render(lexed, filename, template, cb);
+    });
+  }
+}
+
+function loadGtoc(cb) {
+  fs.readFile(gtocPath, 'utf8', function(err, data) {
+    if (err) return cb(err);
+
+    preprocess(gtocPath, data, function(err, data) {
+      if (err) return cb(err);
+
+      data = marked(data).replace(/<a href="(.*?)"/gm, function(a, m) {
+        return '<a class="nav-' + toID(m) + '" href="' + m + '"';
+      });
+      return cb(null, data);
+    });
   });
 }
 
+function toID(filename) {
+  return filename.replace('.html', '').replace(/[^\w\-]/g, '-').replace(/-+/g, '-');
+}
+
 function render(lexed, filename, template, cb) {
   // get the section
   var section = getSection(lexed);
@@ -46,10 +92,17 @@ function render(lexed, filename, template, cb) {
   buildToc(lexed, filename, function(er, toc) {
     if (er) return cb(er);
 
+    var id = toID(path.basename(filename));
+
+    template = template.replace(/__ID__/g, id);
     template = template.replace(/__FILENAME__/g, filename);
     template = template.replace(/__SECTION__/g, section);
     template = template.replace(/__VERSION__/g, process.version);
     template = template.replace(/__TOC__/g, toc);
+    template = template.replace(
+      /__GTOC__/g,
+      gtocData.replace('class="nav-' + id, 'class="nav-' + id + ' active')
+    );
 
     // content has to be the last thing we do with
     // the lexed tokens, because it's destructive.
diff --git a/tools/doc/preprocess.js b/tools/doc/preprocess.js
new file mode 100644
index 0000000000..7ace95a0ad
--- /dev/null
+++ b/tools/doc/preprocess.js
@@ -0,0 +1,57 @@
+module.exports = preprocess;
+
+var path = require('path');
+var fs = require('fs');
+
+var includeExpr = /^@include\s+([A-Za-z0-9-_]+)(?:\.)?([a-zA-Z]*)$/gmi;
+var includeData = {};
+
+function preprocess(inputFile, input, cb) {
+  input = stripComments(input);
+  processIncludes(inputFile, input, function (err, data) {
+    if (err) return cb(err);
+
+    cb(null, data);
+  });
+}
+
+function stripComments(input) {
+  return input.replace(/^@\/\/.*$/gmi, '');
+}
+
+function processIncludes(inputFile, input, cb) {
+  var includes = input.match(includeExpr);
+  if (includes === null) return cb(null, input);
+  var errState = null;
+  console.error(includes);
+  var incCount = includes.length;
+  if (incCount === 0) cb(null, input);
+  includes.forEach(function(include) {
+    var fname = include.replace(/^@include\s+/, '');
+    if (!fname.match(/\.markdown$/)) fname += '.markdown';
+
+    if (includeData.hasOwnProperty(fname)) {
+      input = input.split(include).join(includeData[fname]);
+      incCount--;
+      if (incCount === 0) {
+        return cb(null, input);
+      }
+    }
+
+    var fullFname = path.resolve(path.dirname(inputFile), fname);
+    fs.readFile(fullFname, 'utf8', function(er, inc) {
+      if (errState) return;
+      if (er) return cb(errState = er);
+      preprocess(inputFile, inc, function(er, inc) {
+        if (errState) return;
+        if (er) return cb(errState = er);
+        incCount--;
+        includeData[fname] = inc;
+        input = input.split(include+'\n').join(includeData[fname]+'\n');
+        if (incCount === 0) {
+          return cb(null, input);
+        }
+      });
+    });
+  });
+}