Skip to content

Commit 451f8a7

Browse files
flakey5ovflowd
andcommitted
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 <[email protected]> Co-authored-by: Claudio W <[email protected]>
1 parent 2a6f908 commit 451f8a7

30 files changed

+26
-6096
lines changed

Makefile

+19-71
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ NODE_EXE = node$(EXEEXT)
8282
NODE ?= "$(PWD)/$(NODE_EXE)"
8383
NODE_G_EXE = node_g$(EXEEXT)
8484
NPM ?= ./deps/npm/bin/npm-cli.js
85+
NPX ?= ./deps/npm/bin/npx-cli.js
8586

8687
# Flags for packaging.
8788
BUILD_DOWNLOAD_FLAGS ?= --download=all
@@ -103,6 +104,16 @@ available-node = \
103104
exit 1; \
104105
fi;
105106

107+
available-npx = \
108+
if [ -x "$(NPX)" ] && [ -e "$(NPX)" ]; then \
109+
"$(NPX)" $(1); \
110+
elif [ -x `command -v npx` ] && [ -e `command -v npx` ] && [ `command -v npx` ]; then \
111+
`command -v npx` $(1); \
112+
else \
113+
echo "No available npx, cannot run \"npx $(1)\""; \
114+
exit 1; \
115+
fi;
116+
106117
.PHONY: all
107118
# BUILDTYPE=Debug builds both release and debug builds. If you want to compile
108119
# just the debug build, run `make -C out BUILDTYPE=Debug` instead.
@@ -369,7 +380,7 @@ test-valgrind: all ## Run tests using valgrind.
369380
test-check-deopts: all
370381
$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --check-deopts parallel sequential
371382

372-
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md
383+
DOCBUILDSTAMP_PREREQS = tools/doc/ doc/api/addons.md
373384

374385
ifeq ($(OSTYPE),aix)
375386
DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
@@ -385,7 +396,7 @@ test/addons/.docbuildstamp: $(DOCBUILDSTAMP_PREREQS) tools/doc/node_modules
385396
echo "Skipping .docbuildstamp (no crypto and/or no ICU)"; \
386397
else \
387398
$(RM) -r test/addons/??_*/; \
388-
[ -x $(NODE) ] && $(NODE) $< || node $< ; \
399+
[ -x $(NPM) ] && $(NPM) --prefix $< run addon-verify || npm --prefix $< run addon-verify ; \
389400
[ $$? -eq 0 ] && touch $@; \
390401
fi
391402

@@ -782,11 +793,8 @@ endif
782793
apidoc_dirs = out/doc out/doc/api out/doc/api/assets
783794
skip_apidoc_files = doc/api/quic.md
784795

785-
apidoc_sources = $(filter-out $(skip_apidoc_files), $(wildcard doc/api/*.md))
786-
apidocs_html = $(addprefix out/,$(apidoc_sources:.md=.html))
787-
apidocs_json = $(addprefix out/,$(apidoc_sources:.md=.json))
788-
789-
apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
796+
node_use_icu = $(call available-node,"-p" "typeof Intl === 'object'")
797+
run-npm-ci = $(PWD)/$(NPM) ci
790798

791799
tools/doc/node_modules: tools/doc/package.json
792800
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
@@ -797,11 +805,11 @@ tools/doc/node_modules: tools/doc/package.json
797805

798806
.PHONY: doc-only
799807
doc-only: tools/doc/node_modules \
800-
$(apidoc_dirs) $(apiassets) ## Build the docs with the local or the global Node.js binary.
801-
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
802-
echo "Skipping doc-only (no crypto and/or no ICU)"; \
808+
$(apidoc_dirs) ## Builds the docs with the local or the global Node.js binary.
809+
@if [ "$(shell $(node_use_openssl))" != "true" ] || [ "$(shell $(node_use_icu))" != "true" ]; then \
810+
echo "Skipping doc-only (no crypto or no icu)"; \
803811
else \
804-
$(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \
812+
$(call available-npx, --prefix tools/doc api-docs-tooling -t legacy-html-all legacy-json-all api-links -i doc/api/\*.md -i lib/\*.js -o out/doc/api/ -c file://$(PWD)/CHANGELOG.md) \
805813
fi
806814

807815
.PHONY: doc
@@ -817,66 +825,6 @@ out/doc/api: doc/api
817825
mkdir -p $@
818826
cp -r doc/api out/doc
819827

820-
# If it's a source tarball, assets are already in doc/api/assets
821-
out/doc/api/assets:
822-
mkdir -p $@
823-
if [ -d doc/api/assets ]; then cp -r doc/api/assets out/doc/api; fi;
824-
825-
# If it's not a source tarball, we need to copy assets from doc/api_assets
826-
out/doc/api/assets/%: doc/api_assets/% | out/doc/api/assets
827-
@cp $< $@ ; $(RM) out/doc/api/assets/README.md
828-
829-
830-
run-npm-ci = $(PWD)/$(NPM) ci
831-
832-
LINK_DATA = out/doc/apilinks.json
833-
VERSIONS_DATA = out/previous-doc-versions.json
834-
gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION) \
835-
--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api \
836-
--versions-file=$(VERSIONS_DATA)
837-
gen-apilink = tools/doc/apilinks.mjs $(LINK_DATA) $(wildcard lib/*.js)
838-
839-
$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.mjs | out/doc
840-
$(call available-node, $(gen-apilink))
841-
842-
# Regenerate previous versions data if the current version changes
843-
$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.mjs
844-
$(call available-node, tools/doc/versions.mjs $@)
845-
846-
node_use_icu = $(call available-node,"-p" "typeof Intl === 'object'")
847-
848-
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs \
849-
tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs \
850-
tools/doc/apilinks.mjs $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
851-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
852-
echo "Skipping documentation generation (no ICU)"; \
853-
else \
854-
$(call available-node, $(gen-api)) \
855-
fi
856-
857-
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.mjs \
858-
tools/doc/apilinks.mjs | out/doc/api
859-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
860-
echo "Skipping HTML single-page doc generation (no ICU)"; \
861-
else \
862-
$(call available-node, tools/doc/allhtml.mjs) \
863-
fi
864-
865-
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api
866-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
867-
echo "Skipping JSON single-file generation (no ICU)"; \
868-
else \
869-
$(call available-node, tools/doc/alljson.mjs) \
870-
fi
871-
872-
.PHONY: out/doc/api/stability
873-
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api
874-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
875-
echo "Skipping stability indicator generation (no ICU)"; \
876-
else \
877-
$(call available-node, tools/doc/stability.mjs) \
878-
fi
879-
880828
.PHONY: docopen
881829
docopen: out/doc/api/all.html ## Open the documentation in a web browser.
882830
@$(PYTHON) -mwebbrowser file://$(abspath $<)

doc/api_assets/README.md

-7
This file was deleted.

doc/api_assets/api.js

-216
This file was deleted.

0 commit comments

Comments
 (0)