Commit 6032dc2
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 <christopher.s.dickinson@gmail.com>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>1 parent 6eed6a3 commit 6032dc2
4 files changed
Lines changed: 49 additions & 15 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -52,10 +52,20 @@ $ make test | |||
| 52 | 52 | ||
| 53 | 53 | To build the documentation: | |
| 54 | 54 | ||
| 55 | + This will build Node.js first (if necessary) and then use it to build the docs: | ||
| 56 | + | ||
| 55 | 57 | ```text | |
| 56 | 58 | $ make doc | |
| 57 | 59 | ``` | |
| 58 | 60 | ||
| 61 | + If you have an existing Node.js you can build just the docs with: | ||
| 62 | + | ||
| 63 | + ```text | ||
| 64 | + $ NODE=node make doc-only | ||
| 65 | + ``` | ||
| 66 | + | ||
| 67 | + (Where `node` is the path to your executable.) | ||
| 68 | + | ||
| 59 | 69 | To read the documentation: | |
| 60 | 70 | ||
| 61 | 71 | ```text | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -36,8 +36,8 @@ BUILDTYPE_LOWER := $(shell echo $(BUILDTYPE) | tr '[A-Z]' '[a-z]') | |||
| 36 | 36 | EXEEXT := $(shell $(PYTHON) -c \ | |
| 37 | 37 | "import sys; print('.exe' if sys.platform == 'win32' else '')") | |
| 38 | 38 | ||
| 39 | - NODE ?= ./node$(EXEEXT) | ||
| 40 | 39 | NODE_EXE = node$(EXEEXT) | |
| 40 | + NODE ?= ./$(NODE_EXE) | ||
| 41 | 41 | NODE_G_EXE = node_g$(EXEEXT) | |
| 42 | 42 | ||
| 43 | 43 | # Flags for packaging. | |
@@ -260,7 +260,9 @@ apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets | |||
| 260 | 260 | ||
| 261 | 261 | apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*))) | |
| 262 | 262 | ||
| 263 | - doc: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ $(NODE_EXE) | ||
| 263 | + doc-only: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ | ||
| 264 | + | ||
| 265 | + doc: $(NODE_EXE) doc-only | ||
| 264 | 266 | ||
| 265 | 267 | $(apidoc_dirs): | |
| 266 | 268 | mkdir -p $@ | |
@@ -271,11 +273,11 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets/ | |||
| 271 | 273 | out/doc/%: doc/% | |
| 272 | 274 | cp -r $< $@ | |
| 273 | 275 | ||
| 274 | - out/doc/api/%.json: doc/api/%.md $(NODE_EXE) | ||
| 276 | + out/doc/api/%.json: doc/api/%.md | ||
| 275 | 277 | $(NODE) tools/doc/generate.js --format=json $< > $@ | |
| 276 | 278 | ||
| 277 | - out/doc/api/%.html: doc/api/%.md $(NODE_EXE) | ||
| 278 | - $(NODE) tools/doc/generate.js --format=html --template=doc/template.html $< > $@ | ||
| 279 | + out/doc/api/%.html: doc/api/%.md | ||
| 280 | + $(NODE) tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< > $@ | ||
| 279 | 281 | ||
| 280 | 282 | docopen: out/doc/api/all.html | |
| 281 | 283 | -google-chrome out/doc/api/all.html | |
@@ -694,5 +696,5 @@ endif | |||
| 694 | 696 | blog blogclean tar binary release-only bench-http-simple bench-idle \ | |
| 695 | 697 | bench-all bench bench-misc bench-array bench-buffer bench-net \ | |
| 696 | 698 | bench-http bench-fs bench-tls cctest run-ci test-v8 test-v8-intl \ | |
| 697 | - test-v8-benchmarks test-v8-all v8 lint-ci bench-ci jslint-ci \ | ||
| 699 | + test-v8-benchmarks test-v8-all v8 lint-ci bench-ci jslint-ci doc-only \ | ||
| 698 | 700 | $(TARBALL)-headers | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -10,6 +10,7 @@ const args = process.argv.slice(2); | |||
| 10 | 10 | let format = 'json'; | |
| 11 | 11 | let template = null; | |
| 12 | 12 | let inputFile = null; | |
| 13 | + let nodeVersion = null; | ||
| 13 | 14 | ||
| 14 | 15 | args.forEach(function(arg) { | |
| 15 | 16 | if (!arg.match(/^\-\-/)) { | |
@@ -18,23 +19,22 @@ args.forEach(function(arg) { | |||
| 18 | 19 | format = arg.replace(/^\-\-format=/, ''); | |
| 19 | 20 | } else if (arg.match(/^\-\-template=/)) { | |
| 20 | 21 | template = arg.replace(/^\-\-template=/, ''); | |
| 22 | + } else if (arg.match(/^\-\-node\-version=/)) { | ||
| 23 | + nodeVersion = arg.replace(/^\-\-node\-version=/, ''); | ||
| 21 | 24 | } | |
| 22 | 25 | }); | |
| 23 | 26 | ||
| 24 | - | ||
| 25 | 27 | if (!inputFile) { | |
| 26 | 28 | throw new Error('No input file specified'); | |
| 27 | 29 | } | |
| 28 | 30 | ||
| 29 | - | ||
| 30 | 31 | console.error('Input file = %s', inputFile); | |
| 31 | 32 | fs.readFile(inputFile, 'utf8', function(er, input) { | |
| 32 | 33 | if (er) throw er; | |
| 33 | 34 | // process the input for @include lines | |
| 34 | 35 | processIncludes(inputFile, input, next); | |
| 35 | 36 | }); | |
| 36 | 37 | ||
| 37 | - | ||
| 38 | 38 | function next(er, input) { | |
| 39 | 39 | if (er) throw er; | |
| 40 | 40 | switch (format) { | |
@@ -46,7 +46,12 @@ function next(er, input) { | |||
| 46 | 46 | break; | |
| 47 | 47 | ||
| 48 | 48 | case 'html': | |
| 49 | - require('./html.js')(input, inputFile, template, function(er, html) { | ||
| 49 | + require('./html.js')({ | ||
| 50 | + input: input, | ||
| 51 | + filename: inputFile, | ||
| 52 | + template: template, | ||
| 53 | + nodeVersion: nodeVersion, | ||
| 54 | + }, function(er, html) { | ||
| 50 | 55 | if (er) throw er; | |
| 51 | 56 | console.log(html); | |
| 52 | 57 | }); | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -30,7 +30,12 @@ var gtocPath = path.resolve(path.join( | |||
| 30 | 30 | var gtocLoading = null; | |
| 31 | 31 | var gtocData = null; | |
| 32 | 32 | ||
| 33 | - function toHTML(input, filename, template, cb) { | ||
| 33 | + /** | ||
| 34 | + * opts: input, filename, template, nodeVersion. | ||
| 35 | + */ | ||
| 36 | + function toHTML(opts, cb) { | ||
| 37 | + var template = opts.template; | ||
| 38 | + | ||
| 34 | 39 | if (gtocData) { | |
| 35 | 40 | return onGtocLoaded(); | |
| 36 | 41 | } | |
@@ -51,10 +56,15 @@ function toHTML(input, filename, template, cb) { | |||
| 51 | 56 | } | |
| 52 | 57 | ||
| 53 | 58 | function onGtocLoaded() { | |
| 54 | - var lexed = marked.lexer(input); | ||
| 59 | + var lexed = marked.lexer(opts.input); | ||
| 55 | 60 | fs.readFile(template, 'utf8', function(er, template) { | |
| 56 | 61 | if (er) return cb(er); | |
| 57 | - render(lexed, filename, template, cb); | ||
| 62 | + render({ | ||
| 63 | + lexed: lexed, | ||
| 64 | + filename: opts.filename, | ||
| 65 | + template: template, | ||
| 66 | + nodeVersion: opts.nodeVersion, | ||
| 67 | + }, cb); | ||
| 58 | 68 | }); | |
| 59 | 69 | } | |
| 60 | 70 | } | |
@@ -81,7 +91,14 @@ function toID(filename) { | |||
| 81 | 91 | .replace(/-+/g, '-'); | |
| 82 | 92 | } | |
| 83 | 93 | ||
| 84 | - function render(lexed, filename, template, cb) { | ||
| 94 | + /** | ||
| 95 | + * opts: lexed, filename, template, nodeVersion. | ||
| 96 | + */ | ||
| 97 | + function render(opts, cb) { | ||
| 98 | + var lexed = opts.lexed; | ||
| 99 | + var filename = opts.filename; | ||
| 100 | + var template = opts.template; | ||
| 101 | + | ||
| 85 | 102 | // get the section | |
| 86 | 103 | var section = getSection(lexed); | |
| 87 | 104 | ||
@@ -100,7 +117,7 @@ function render(lexed, filename, template, cb) { | |||
| 100 | 117 | template = template.replace(/__ID__/g, id); | |
| 101 | 118 | template = template.replace(/__FILENAME__/g, filename); | |
| 102 | 119 | template = template.replace(/__SECTION__/g, section); | |
| 103 | - template = template.replace(/__VERSION__/g, process.version); | ||
| 120 | + template = template.replace(/__VERSION__/g, opts.nodeVersion); | ||
| 104 | 121 | template = template.replace(/__TOC__/g, toc); | |
| 105 | 122 | template = template.replace( | |
| 106 | 123 | /__GTOC__/g, | |
0 commit comments