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

@@ -52,10 +52,20 @@ $ make test
 
 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.
@@ -260,7 +260,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 $@
@@ -271,11 +273,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
@@ -694,5 +696,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);
 letformat='json';
 lettemplate=null;
 letinputFile=null;
+letnodeVersion=null;
 
 args.forEach(function(arg){
 if(!arg.match(/^\-\-/)){
@@ -18,23 +19,22 @@ args.forEach(function(arg){
 format=arg.replace(/^\-\-format=/,'');
 }elseif(arg.match(/^\-\-template=/)){
 template=arg.replace(/^\-\-template=/,'');
+}elseif(arg.match(/^\-\-node\-version=/)){
+nodeVersion=arg.replace(/^\-\-node\-version=/,'');
 }
 });
 
-
 if(!inputFile){
 thrownewError('No input file specified');
 }
 
-
 console.error('Input file = %s',inputFile);
 fs.readFile(inputFile,'utf8',function(er,input){
 if(er)thrower;
 // process the input for @include lines
 processIncludes(inputFile,input,next);
 });
 
-
 functionnext(er,input){
 if(er)thrower;
 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)thrower;
 console.log(html);
 });

tools/doc/html.js

@@ -30,7 +30,12 @@ var gtocPath = path.resolve(path.join(
 vargtocLoading=null;
 vargtocData=null;
 
-functiontoHTML(input,filename,template,cb){
+/**
+ * opts: input, filename, template, nodeVersion.
+ */
+functiontoHTML(opts,cb){
+vartemplate=opts.template;
+
 if(gtocData){
 returnonGtocLoaded();
 }
@@ -51,10 +56,15 @@ function toHTML(input, filename, template, cb){
 }
 
 functiononGtocLoaded(){
-varlexed=marked.lexer(input);
+varlexed=marked.lexer(opts.input);
 fs.readFile(template,'utf8',function(er,template){
 if(er)returncb(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,'-');
 }
 
-functionrender(lexed,filename,template,cb){
+/**
+ * opts: lexed, filename, template, nodeVersion.
+ */
+functionrender(opts,cb){
+varlexed=opts.lexed;
+varfilename=opts.filename;
+vartemplate=opts.template;
+
 // get the section
 varsection=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,