build, doc: use new api doc tooling

Switches over to using the new doc generation tooling.
For more background on this, please see #52343

Signed-off-by: flakey5 <73616808+flakey5@users.noreply.github.com>

Co-authored-by: Claudio W <cwunder@gnome.org>
Co-authored-by: avivkeller <me@aviv.sh>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>

Author: 5 people

.github/CODEOWNERS

@@ -23,8 +23,6 @@
 /onboarding.md @nodejs/tsc
 
 # nodejs.org website
-/doc/api_assets @nodejs/nodejs-website
-/doc/template.html @nodejs/nodejs-website
 /tools/doc @nodejs/web-infra
 
 # streams

.github/workflows/tools.yml

@@ -119,6 +119,12 @@ jobs:
             run: |
               make corepack-update
               echo "NEW_VERSION=$(node deps/corepack/dist/corepack.js --version)" >> $GITHUB_ENV
+          - id: doc
+            subsystem: tools
+            label: tools
+            run: |
+              cd tools/doc
+              ./update.sh
           - id: googletest
             subsystem: deps
             label: dependencies, test

Makefile

@@ -26,8 +26,12 @@ FIND ?= find
 
 ifdef JOBS
 	PARALLEL_ARGS = -j $(JOBS)
+
+	# Amount of worker threads to create for generating documentation files
+	DOC_JOBS = $(JOBS)
 else
 	PARALLEL_ARGS =
+	DOC_JOBS = 12
 endif
 
 ifdef ENABLE_V8_TAP
@@ -101,7 +105,7 @@ V ?= 0
 # 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 \
@@ -340,7 +344,6 @@ coverage-run-js: ## Run JavaScript tests with coverage.
 # 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
@@ -376,7 +379,7 @@ test-valgrind: all ## Run tests using valgrind.
 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
@@ -385,14 +388,16 @@ ifeq ($(OSTYPE),os400)
 DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
 endif
 
+DOC_KIT ?= tools/doc/node_modules/.bin/doc-kit
+
 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
 
@@ -791,29 +796,30 @@ test-v8 test-v8-intl test-v8-benchmarks test-v8-all:
 	$(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 \
+	if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
 		echo "Skipping tools/doc/node_modules (no crypto and/or no ICU)"; \
 	else \
 		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.
+	$(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.
 	@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; \
+		echo "Skipping doc-only (no crypto or no icu)"; \
 	fi
 
 .PHONY: doc
@@ -829,82 +835,46 @@ out/doc/api: doc/api
 	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)"; \
-	else \
-		$(call available-node, tools/doc/alljson.mjs) \
-	fi
+# 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
+$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(apidoc_sources) tools/doc/node_modules | out/doc/api
+	$(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 \
+	)
 
-.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)"; \
-	else \
-		$(call available-node, tools/doc/stability.mjs) \
-	fi
+out/doc/apilinks.json: $(wildcard lib/*.js) | out/doc
+	$(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 \
+	) \
 
 .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

doc/api/synopsis.md

@@ -1,11 +1,11 @@
 # Usage and example
 
-## Usage
-
 <!--introduced_in=v0.10.0-->
 
 <!--type=misc-->
 
+## Usage
+
 `node [options] [V8 options] [script.js | -e "script" | - ] [arguments]`
 
 Please see the [Command-line options][] document for more information.