From 101dd1ed789175311ab22f9a32dfc480f127bc68 Mon Sep 17 00:00:00 2001 From: Jesse McCarthy Date: Wed, 18 Nov 2015 17:40:03 -0500 Subject: [PATCH] build: add Make `doc-only` target Allows building just docs using existing Node instead of building Node first. PR-URL: https://github.com/nodejs/node/pull/3888 Reviewed-By: Chris Dickinson Reviewed-By: Rod Vagg Reviewed-By: James M Snell Reviewed-By: Myles Borins --- BUILDING.md | 10 ++++++++++ Makefile | 14 ++++++++------ tools/doc/generate.js | 13 +++++++++---- tools/doc/html.js | 27 ++++++++++++++++++++++----- 4 files changed, 49 insertions(+), 15 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 7e52658eec8c35..e9bf0bc01337f2 100644 --- a/BUILDING.md +++ b/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 diff --git a/Makefile b/Makefile index 43249b77f1b953..0693e5a1643f32 100644 --- a/Makefile +++ b/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 diff --git a/tools/doc/generate.js b/tools/doc/generate.js index 9048b484ce4e07..94c0905468f862 100644 --- a/tools/doc/generate.js +++ b/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,15 +19,15 @@ 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; @@ -34,7 +35,6 @@ fs.readFile(inputFile, 'utf8', function(er, input) { 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); }); diff --git a/tools/doc/html.js b/tools/doc/html.js index 5f349abe7145b3..45d0a809143a8f 100644 --- a/tools/doc/html.js +++ b/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,