Skip to content

Commit

Permalink
build: add Make doc-only target
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
jmm authored and Myles Borins committed Jul 14, 2016
1 parent ed193ad commit da1e13f
Show file tree
Hide file tree
Showing 4 changed files with 49 additions and 15 deletions.
10 changes: 10 additions & 0 deletions BUILDING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 8 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,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.
Expand Down Expand Up @@ -259,7 +259,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 $@
Expand All @@ -270,11 +272,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
Expand Down Expand Up @@ -664,4 +666,4 @@ lint-ci: lint
bench-all bench bench-misc bench-array bench-buffer bench-net \
bench-http bench-fs bench-tls cctest run-ci lint-ci bench-ci \
test-v8 test-v8-intl test-v8-benchmarks test-v8-all v8 \
$(TARBALL)-headers test-ci test-ci-native test-ci-js build-ci
$(TARBALL)-headers test-ci test-ci-native test-ci-js build-ci doc-only
13 changes: 9 additions & 4 deletions tools/doc/generate.js
Original file line number Diff line number Diff line change
Expand Up @@ -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(/^\-\-/)) {
Expand All @@ -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) {
Expand All @@ -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);
});
Expand Down
27 changes: 22 additions & 5 deletions tools/doc/html.js
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
Expand All @@ -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);
});
}
}
Expand All @@ -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);

Expand All @@ -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,
Expand Down

0 comments on commit da1e13f

Please sign in to comment.