Browse Source

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 <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>
process-exit-stdio-flushing
Jesse McCarthy 9 years ago
committed by Myles Borins
parent
commit
101dd1ed78
  1. 10
      BUILDING.md
  2. 14
      Makefile
  3. 13
      tools/doc/generate.js
  4. 27
      tools/doc/html.js

10
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

14
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

13
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);
});

27
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,

Loading…
Cancel
Save