build, doc: use new api doc tooling · nodejs/node@e55edde

# Use -e to double check in case it's a broken link

available-node = \

if [ -x '$(NODE)' ] && [ -e '$(NODE)' ]; then \

'$(NODE)' $(1); \

PATH='$(PWD)/out/$(BUILDTYPE):$$PATH' '$(NODE)' $(1); \

elif [ -x `command -v node` ] && [ -e `command -v node` ] && [ `command -v node` ]; then \

`command -v node` $(1); \

else \

# This does not run tests of third-party libraries inside deps.

test: all ## Run default tests, linters, and build docs.

$(MAKE) -s tooltest

$(MAKE) -s test-doc

$(MAKE) -s build-addons

$(MAKE) -s build-js-native-api-tests

$(MAKE) -s build-node-api-tests

test-check-deopts: all

$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --check-deopts parallel sequential

DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md

DOCBUILDSTAMP_PREREQS = doc/api/addons.md

ifeq ($(OSTYPE),aix)

DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp

DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp

endif

DOC_KIT ?= tools/doc/node_modules/@nodejs/doc-kit/bin/cli.mjs

node_use_openssl_and_icu = $(call available-node,"-p" \

"process.versions.openssl != undefined && process.versions.icu != undefined")

test/addons/.docbuildstamp: $(DOCBUILDSTAMP_PREREQS) tools/doc/node_modules

@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \

echo "Skipping .docbuildstamp (no crypto and/or no ICU)"; \

else \

$(RM) -r test/addons/??_*/; \

[ -x '$(NODE)' ] && '$(NODE)' $< || node $< ; \

$(call available-node, \

$(DOC_KIT) generate \

-t addon-verify \

-i doc/api/addons.md \

-o test/addons/ \

--type-map doc/type-map.json \

) \

[ $$? -eq 0 ] && touch $@; \

fi

$(warning Use the git repo instead: $$ git clone https://github.com/nodejs/node.git)

endif

apidoc_dirs = out/doc out/doc/api out/doc/api/assets

apidoc_dirs = out/doc out/doc/api

skip_apidoc_files = doc/api/quic.md

apidoc_sources = $(filter-out $(skip_apidoc_files), $(wildcard doc/api/*.md))

apidocs_html = $(addprefix out/,$(apidoc_sources:.md=.html))

apidocs_json = $(addprefix out/,$(apidoc_sources:.md=.json))

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

run-npm-ci = $(PWD)/$(NPM) ci --omit=dev

tools/doc/node_modules: tools/doc/package.json

@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \

cd tools/doc && $(call available-node,$(run-npm-ci)) \

fi

RAWVER=$(shell $(PYTHON) tools/getnodeversion.py)

VERSION=v$(RAWVER)

.PHONY: doc-only

doc-only: tools/doc/node_modules \

$(apidoc_dirs) $(apiassets) ## Build the docs with the local or the global Node.js binary.

@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \

echo "Skipping doc-only (no crypto and/or no ICU)"; \

else \

$(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \

fi

.NOTPARALLEL: doc-only

doc-only: $(apidoc_dirs) $(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json out/doc/apilinks.json ## Builds the docs with the local or the global Node.js binary.

.PHONY: doc

doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.

mkdir -p $@

cp -r doc/api out/doc

# If it's a source tarball, assets are already in doc/api/assets

out/doc/api/assets:

mkdir -p $@

if [ -d doc/api/assets ]; then cp -r doc/api/assets out/doc/api; fi;

# If it's not a source tarball, we need to copy assets from doc/api_assets

out/doc/api/assets/%: doc/api_assets/% | out/doc/api/assets

@cp $< $@ ; $(RM) out/doc/api/assets/README.md

run-npm-ci = '$(PWD)/$(NPM)' ci

LINK_DATA = out/doc/apilinks.json

VERSIONS_DATA = out/previous-doc-versions.json

gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION) \

--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api \

--versions-file=$(VERSIONS_DATA)

gen-apilink = tools/doc/apilinks.mjs $(LINK_DATA) $(wildcard lib/*.js)

$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.mjs | out/doc

$(call available-node, $(gen-apilink))

# Regenerate previous versions data if the current version changes

$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.mjs

$(call available-node, tools/doc/versions.mjs $@)

node_use_icu = $(call available-node,"-p" "typeof Intl === 'object'")

out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs \

tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs \

tools/doc/apilinks.mjs $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api

@if [ "$(shell $(node_use_icu))" != "true" ]; then \

echo "Skipping documentation generation (no ICU)"; \

else \

$(call available-node, $(gen-api)) \

fi

out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.mjs \

tools/doc/apilinks.mjs | out/doc/api

@if [ "$(shell $(node_use_icu))" != "true" ]; then \

echo "Skipping HTML single-page doc generation (no ICU)"; \

else \

$(call available-node, tools/doc/allhtml.mjs) \

fi

out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api

@if [ "$(shell $(node_use_icu))" != "true" ]; then \

echo "Skipping JSON single-file generation (no ICU)"; \

# Generate all doc files (individual and all.html/all.json) in a single doc-kit call

# Using grouped targets (&:) so Make knows one command produces all outputs

ifeq ($(OSTYPE),aix)

# TODO(@nodejs/web-infra): AIX is currently hanging during HTML minification

$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json:

@echo "Skipping $@ (not currently supported by $(OSTYPE) machines)"

else

$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(apidoc_sources) tools/doc/node_modules | out/doc/api

@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \

echo "Skipping $@ (no crypto and/or no ICU)"; \

else \

$(call available-node, tools/doc/alljson.mjs) \

$(call available-node, \

$(DOC_KIT) generate \

-t legacy-html-all \

-t legacy-json-all \

-i doc/api/*.md \

--ignore $(skip_apidoc_files) \

-o out/doc/api \

-c ./CHANGELOG.md \

-v $(VERSION) \

--index doc/api/index.md \

--type-map doc/type-map.json \

) \

fi

endif

.PHONY: out/doc/api/stability

out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api

@if [ "$(shell $(node_use_icu))" != "true" ]; then \

echo "Skipping stability indicator generation (no ICU)"; \

out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc

@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \

echo "Skipping $@ (no crypto and/or no ICU)"; \

else \

$(call available-node, tools/doc/stability.mjs) \

$(call available-node, \

$(DOC_KIT) generate \

-t api-links \

-i lib/*.js \

-o $(@D) \

-c ./CHANGELOG.md \

-v $(VERSION) \

--type-map doc/type-map.json \

) \

fi

.PHONY: docopen

docopen: out/doc/api/all.html ## Open the documentation in a web browser.

docopen: doc-only ## Open the documentation in a web browser.

@$(PYTHON) -mwebbrowser file://$(abspath $<)

.PHONY: docserve

docserve: $(apidocs_html) $(apiassets) ## Serve the documentation on localhost:8000.

docserve: doc-only ## Serve the documentation on localhost:8000.

@$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api

.PHONY: docclean

.NOTPARALLEL: docclean

docclean: ## Remove the generated documentation.

$(RM) -r out/doc

$(RM) "$(VERSIONS_DATA)"

RAWVER=$(shell $(PYTHON) tools/getnodeversion.py)

VERSION=v$(RAWVER)

CHANGELOG=doc/changelogs/CHANGELOG_V$(firstword $(subst ., ,$(RAWVER))).md

# For nightly builds, you must set DISTTYPE to "nightly", "next-nightly" or