Skip to content

Add task for building docs only, using existing Node

Rodrigo Muino Tomonari requested to merge github/fork/jmm/build-just-docs into master

This is a WIP attempt to make it easy to build just the docs using an existing Node, instead of having to build Node first, which can be prohibitively slow. Related #3749. The primary reason I call it a WIP is because Make is not my forte :/

/cc @nodejs/documentation @chrisdickinson (per suggestion).

I saw that in Makefile there's a conditionally set NODE var that's used for building the docs (among other things), so I based this on utilizing that: NODE=node make doc-only.

Summary of changes:

  • When it's not explicitly set, set NODE using NODE_EXE to reduce duplication.
  • Setup tools/doc/generate.js to read a --node-version argument, which will be used to output the version to the docs instead of process.version. Setup the relevant Make recipe to pass it.
  • Refactor tools/doc/html.js's toHTML and render() to accept options hashes (the signatures would be getting pretty unwieldy if I'd added node_version, which I'm propagating to those functions from generate.js).
  • Make targets
    • I added a doc-only phony target.
    • I made $(NODE_EXE) and doc-only prerequisites of doc.
    • I removed $(NODE_EXE) as a prerequisite of the out/doc/api/%.json and out/doc/api/%.html targets. I'm hoping that it being a prerequisite of doc takes care of it for any case where it's needed by these targets (the only one I'm sure of is make doc).

The changes to the Make targets are the parts I'm least confident about. I'd appreciate if someone who understands Make better can check that it's a sensible setup, and especially that it won't break stuff.

Merge request reports

Loading