build: add Make doc-only target

Allows building just docs using existing Node instead of building Node
first.

PR-URL: #3888
Reviewed-By: Chris Dickinson <[email protected]>
Reviewed-By: Rod Vagg <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Myles Borins <[email protected]>

Author: jmm

BUILDING.md

@@ -67,10 +67,20 @@ $ make test-npm
 
 To build the documentation:
 
+This will build Node.js first (if necessary) and then use it to build the docs:
+
 ```text
 $ make doc
 ```
 
+If you have an existing Node.js you can build just the docs with:
+
+```text
+$ NODE=node make doc-only
+```
+
+(Where `node` is the path to your executable.)
+
 To read the documentation:
 
 ```text

Makefile

@@ -36,8 +36,8 @@ BUILDTYPE_LOWER := $(shell echo $(BUILDTYPE) | tr '[A-Z]' '[a-z]')
 EXEEXT := $(shell $(PYTHON) -c \
 		"import sys; print('.exe' if sys.platform == 'win32' else '')")
 
-NODE ?= ./node$(EXEEXT)
 NODE_EXE = node$(EXEEXT)
+NODE ?= ./$(NODE_EXE)
 NODE_G_EXE = node_g$(EXEEXT)
 
 # Flags for packaging.
@@ -258,7 +258,9 @@ apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets
 
 apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
 
-doc: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ $(NODE_EXE)
+doc-only: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/
+
+doc: $(NODE_EXE) doc-only
 
 $(apidoc_dirs):
 	mkdir -p $@
@@ -269,11 +271,11 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets/
 out/doc/%: doc/%
 	cp -r $< $@
 
-out/doc/api/%.json: doc/api/%.md $(NODE_EXE)
+out/doc/api/%.json: doc/api/%.md
 	$(NODE) tools/doc/generate.js --format=json $< > $@
 
-out/doc/api/%.html: doc/api/%.md $(NODE_EXE)
-	$(NODE) tools/doc/generate.js --format=html --template=doc/template.html $< > $@
+out/doc/api/%.html: doc/api/%.md
+	$(NODE) tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< > $@
 
 docopen: out/doc/api/all.html
 	-google-chrome out/doc/api/all.html
@@ -663,5 +665,5 @@ endif
 	blog blogclean tar binary release-only bench-http-simple bench-idle \
 	bench-all bench bench-misc bench-array bench-buffer bench-net \
 	bench-http bench-fs bench-tls cctest run-ci test-v8 test-v8-intl \
-	test-v8-benchmarks test-v8-all v8 lint-ci bench-ci jslint-ci \
+	test-v8-benchmarks test-v8-all v8 lint-ci bench-ci jslint-ci doc-only \
 	$(TARBALL)-headers

tools/doc/generate.js

@@ -10,6 +10,7 @@ const args = process.argv.slice(2);
 let format = 'json';
 let template = null;
 let inputFile = null;
+let nodeVersion = null;
 
 args.forEach(function(arg) {
   if (!arg.match(/^\-\-/)) {
@@ -18,23 +19,22 @@ args.forEach(function(arg) {
     format = arg.replace(/^\-\-format=/, '');
   } else if (arg.match(/^\-\-template=/)) {
     template = arg.replace(/^\-\-template=/, '');
+  } else if (arg.match(/^\-\-node\-version=/)) {
+    nodeVersion = arg.replace(/^\-\-node\-version=/, '');
   }
 });
 
-
 if (!inputFile) {
   throw new Error('No input file specified');
 }
 
-
 console.error('Input file = %s', inputFile);
 fs.readFile(inputFile, 'utf8', function(er, input) {
   if (er) throw er;
   // process the input for @include lines
   processIncludes(inputFile, input, next);
 });
 
-
 function next(er, input) {
   if (er) throw er;
   switch (format) {
@@ -46,7 +46,12 @@ function next(er, input) {
       break;
 
     case 'html':
-      require('./html.js')(input, inputFile, template, function(er, html) {
+      require('./html.js')({
+        input: input,
+        filename: inputFile,
+        template: template,
+        nodeVersion: nodeVersion,
+      }, function(er, html) {
         if (er) throw er;
         console.log(html);
       });

tools/doc/html.js

@@ -30,7 +30,12 @@ var gtocPath = path.resolve(path.join(
 var gtocLoading = null;
 var gtocData = null;
 
-function toHTML(input, filename, template, cb) {
+/**
+ * opts: input, filename, template, nodeVersion.
+ */
+function toHTML(opts, cb) {
+  var template = opts.template;
+
   if (gtocData) {
     return onGtocLoaded();
   }
@@ -51,10 +56,15 @@ function toHTML(input, filename, template, cb) {
   }
 
   function onGtocLoaded() {
-    var lexed = marked.lexer(input);
+    var lexed = marked.lexer(opts.input);
     fs.readFile(template, 'utf8', function(er, template) {
       if (er) return cb(er);
-      render(lexed, filename, template, cb);
+      render({
+        lexed: lexed,
+        filename: opts.filename,
+        template: template,
+        nodeVersion: opts.nodeVersion,
+      }, cb);
     });
   }
 }
@@ -81,7 +91,14 @@ function toID(filename) {
     .replace(/-+/g, '-');
 }
 
-function render(lexed, filename, template, cb) {
+/**
+ * opts: lexed, filename, template, nodeVersion.
+ */
+function render(opts, cb) {
+  var lexed = opts.lexed;
+  var filename = opts.filename;
+  var template = opts.template;
+
   // get the section
   var section = getSection(lexed);
 
@@ -100,7 +117,7 @@ function render(lexed, filename, template, cb) {
     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(/__VERSION__/g, opts.nodeVersion);
     template = template.replace(/__TOC__/g, toc);
     template = template.replace(
       /__GTOC__/g,