Sitelet https://github.com/nodejs/node/commit/da1e13fde7
Skip to content

Commit da1e13f

Browse files
jmmMyles Borins
jmm
authored and
Myles Borins
committed
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 ed193ad commit da1e13f

4 files changed

Lines changed: 49 additions & 15 deletions

File tree

‎BUILDING.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,10 +67,20 @@ $ make test-npm
6767

6868
To build the documentation:
6969

70+
This will build Node.js first (if necessary) and then use it to build the docs:
71+
7072
```text
7173
$ make doc
7274
```
7375

76+
If you have an existing Node.js you can build just the docs with:
77+
78+
```text
79+
$ NODE=node make doc-only
80+
```
81+
82+
(Where `node` is the path to your executable.)
83+
7484
To read the documentation:
7585

7686
```text

‎Makefile‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ BUILDTYPE_LOWER := $(shell echo $(BUILDTYPE) | tr '[A-Z]' '[a-z]')
3232
EXEEXT := $(shell $(PYTHON) -c \
3333
"import sys; print('.exe' if sys.platform == 'win32' else '')")
3434

35-
NODE ?= ./node$(EXEEXT)
3635
NODE_EXE = node$(EXEEXT)
36+
NODE ?= ./$(NODE_EXE)
3737
NODE_G_EXE = node_g$(EXEEXT)
3838

3939
# Flags for packaging.
@@ -259,7 +259,9 @@ apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets
259259

260260
apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
261261

262-
doc: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ $(NODE_EXE)
262+
doc-only: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/
263+
264+
doc: $(NODE_EXE) doc-only
263265

264266
$(apidoc_dirs):
265267
mkdir -p $@
@@ -270,11 +272,11 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets/
270272
out/doc/%: doc/%
271273
cp -r $< $@
272274

273-
out/doc/api/%.json: doc/api/%.md $(NODE_EXE)
275+
out/doc/api/%.json: doc/api/%.md
274276
$(NODE) tools/doc/generate.js --format=json $< > $@
275277

276-
out/doc/api/%.html: doc/api/%.md $(NODE_EXE)
277-
$(NODE) tools/doc/generate.js --format=html --template=doc/template.html $< > $@
278+
out/doc/api/%.html: doc/api/%.md
279+
$(NODE) tools/doc/generate.js --node-version=$(FULLVERSION) --format=html --template=doc/template.html $< > $@
278280

279281
docopen: out/doc/api/all.html
280282
-google-chrome out/doc/api/all.html
@@ -664,4 +666,4 @@ lint-ci: lint
664666
bench-all bench bench-misc bench-array bench-buffer bench-net \
665667
bench-http bench-fs bench-tls cctest run-ci lint-ci bench-ci \
666668
test-v8 test-v8-intl test-v8-benchmarks test-v8-all v8 \
667-
$(TARBALL)-headers test-ci test-ci-native test-ci-js build-ci
669+
$(TARBALL)-headers test-ci test-ci-native test-ci-js build-ci doc-only

‎tools/doc/generate.js‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ const args = process.argv.slice(2);
1010
let format = 'json';
1111
let template = null;
1212
let inputFile = null;
13+
let nodeVersion = null;
1314

1415
args.forEach(function(arg) {
1516
if (!arg.match(/^\-\-/)) {
@@ -18,23 +19,22 @@ args.forEach(function(arg) {
1819
format = arg.replace(/^\-\-format=/, '');
1920
} else if (arg.match(/^\-\-template=/)) {
2021
template = arg.replace(/^\-\-template=/, '');
22+
} else if (arg.match(/^\-\-node\-version=/)) {
23+
nodeVersion = arg.replace(/^\-\-node\-version=/, '');
2124
}
2225
});
2326

24-
2527
if (!inputFile) {
2628
throw new Error('No input file specified');
2729
}
2830

29-
3031
console.error('Input file = %s', inputFile);
3132
fs.readFile(inputFile, 'utf8', function(er, input) {
3233
if (er) throw er;
3334
// process the input for @include lines
3435
processIncludes(inputFile, input, next);
3536
});
3637

37-
3838
function next(er, input) {
3939
if (er) throw er;
4040
switch (format) {
@@ -46,7 +46,12 @@ function next(er, input) {
4646
break;
4747

4848
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) {
5055
if (er) throw er;
5156
console.log(html);
5257
});

‎tools/doc/html.js‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,12 @@ var gtocPath = path.resolve(path.join(
3030
var gtocLoading = null;
3131
var gtocData = null;
3232

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+
3439
if (gtocData) {
3540
return onGtocLoaded();
3641
}
@@ -51,10 +56,15 @@ function toHTML(input, filename, template, cb) {
5156
}
5257

5358
function onGtocLoaded() {
54-
var lexed = marked.lexer(input);
59+
var lexed = marked.lexer(opts.input);
5560
fs.readFile(template, 'utf8', function(er, template) {
5661
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);
5868
});
5969
}
6070
}
@@ -81,7 +91,14 @@ function toID(filename) {
8191
.replace(/-+/g, '-');
8292
}
8393

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+
85102
// get the section
86103
var section = getSection(lexed);
87104

@@ -100,7 +117,7 @@ function render(lexed, filename, template, cb) {
100117
template = template.replace(/__ID__/g, id);
101118
template = template.replace(/__FILENAME__/g, filename);
102119
template = template.replace(/__SECTION__/g, section);
103-
template = template.replace(/__VERSION__/g, process.version);
120+
template = template.replace(/__VERSION__/g, opts.nodeVersion);
104121
template = template.replace(/__TOC__/g, toc);
105122
template = template.replace(
106123
/__GTOC__/g,

0 commit comments

Comments
 (0)