doc, tools: refactor html generation

Makefile

@@ -284,7 +284,7 @@ out/doc/api/%.json: doc/api/%.md
 	[ -x $(NODE) ] && $(NODE) $(gen-json) || node $(gen-json)
 
 # check if ./node is actually set, else use user pre-installed binary
-gen-html = tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< > $@
+gen-html = tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $<
 out/doc/api/%.html: doc/api/%.md
 	[ -x $(NODE) ] && $(NODE) $(gen-html) || node $(gen-html)
 

doc/guides/_toc.md

@@ -0,0 +1,11 @@
+* [About these Docs](documentation.html)
+* [Usage & Example](synopsis.html)
+
+<div class="line"></div>
+
+* [Building Node With Ninja](building-node-with-ninja.html)
+
+<div class="line"></div>
+
+* [GitHub Repo & Issue Tracker](https://github.com/nodejs/node)
+* [Mailing List](http://groups.google.com/group/nodejs)

test/doctool/test-doctool-html.js

@@ -5,7 +5,10 @@ const assert = require('assert');
 const fs = require('fs');
 const path = require('path');
 
-const html = require('../../tools/doc/html.js');
+common.globalCheck = false;
+
+const processIncludes = require('../../tools/doc/preprocess.js');
+const html = require('../../tools/doc/html.js').toHTML;
 
 // Test data is a list of objects with two properties.
 // The file property is the file path.
@@ -53,22 +56,43 @@ const testData = [
       '<p>Describe <code>Something</code> in more detail here. ' +
       '</p>'
   },
+  {
+    file: path.join(common.fixturesDir, 'doc_with_includes.md'),
+    html: '<!-- [start-include:doc_inc_1.md] -->' +
+    '<p>Look <a href="doc_inc_2.html#doc_inc_2_foobar">here</a>!</p>' +
+    '<!-- [end-include:doc_inc_1.md] -->' +
+    '<!-- [start-include:doc_inc_2.md] -->' +
+    '<h1>foobar<span><a class="mark" href="#doc_inc_2_foobar" ' +
+    'id="doc_inc_2_foobar">#</a></span></h1>' +
+    '<p>I exist and am being linked to.</p>' +
+    '<!-- [end-include:doc_inc_2.md] -->'
+  },
 ];
 
 testData.forEach(function(item) {
   // Normalize expected data by stripping whitespace
   const expected = item.html.replace(/\s/g, '');
 
-  fs.readFile(item.file, 'utf8', common.mustCall(function(err, input) {
+  fs.readFile(item.file, 'utf8', common.mustCall((err, input) => {
     assert.ifError(err);
-    html(input, 'foo', 'doc/template.html',
-      common.mustCall(function(err, output) {
-        assert.ifError(err);
+    processIncludes(item.file, input, common.mustCall((err, preprocessed) => {
+      assert.ifError(err);
+
+      html(
+        {
+          input: preprocessed,
+          filename: 'foo',
+          template: 'doc/template.html',
+          nodeVersion: process.version,
+        },
+        common.mustCall((err, output) => {
+          assert.ifError(err);
 
-        const actual = output.replace(/\s/g, '');
-        // Assert that the input stripped of all whitespace contains the
-        // expected list
-        assert.notEqual(actual.indexOf(expected), -1);
-      }));
+          const actual = output.replace(/\s/g, '');
+          // Assert that the input stripped of all whitespace contains the
+          // expected list
+          assert.notEqual(actual.indexOf(expected), -1);
+        }));
+    }));
   }));
 });

tools/doc/generate.js

@@ -2,6 +2,8 @@
 
 const processIncludes = require('./preprocess.js');
 const fs = require('fs');
+const path = require('path');
+const toHTML = require('./html.js').toHTML;
 
 // parse the args.
 // Don't use nopt or whatever for this.  It's simple enough.
@@ -48,11 +50,15 @@ function next(er, input) {
       break;
 
     case 'html':
-      require('./html.js')(input, inputFile, template, nodeVersion,
-        function(er, html) {
-          if (er) throw er;
-          console.log(html);
+      toHTML(input, inputFile, template, nodeVersion, (er, html) => {
+        if (er) throw er;
+        const filename = `./out/doc/api/${path.basename(inputFile, 'md')}html`;
+        fs.writeFile(filename, html, (err) => {
+          if (err)
+            console.log(err);
+          console.log('generated:', filename);
         });
+      });
       break;
 
     default: