Skip to content

Commit e55edde

Browse files
flakey55 peopleauthored and
richardlau
committed
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> PR-URL: #57343 Reviewed-By: Claudio Wunder <cwunder@gnome.org> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Aviv Keller <me@aviv.sh> Reviewed-By: Daniel Lemire <daniel@lemire.me> Reviewed-By: Jithil P Ponnan <jithil@outlook.com> Reviewed-By: Filip Skokan <panva.ip@gmail.com>
1 parent 31e7936 commit e55edde

File tree

58 files changed

+4552
-5579
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+4552
-5579
lines changed

‎.github/CODEOWNERS‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,6 @@
2323
/onboarding.md @nodejs/tsc
2424

2525
# nodejs.org website
26-
/doc/api_assets @nodejs/nodejs-website
27-
/doc/template.html @nodejs/nodejs-website
2826
/tools/doc @nodejs/web-infra
2927

3028
# streams

‎.github/workflows/tools.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,14 @@ jobs:
121121
run: |
122122
make corepack-update
123123
echo "NEW_VERSION=$(node deps/corepack/dist/corepack.js --version)" >> $GITHUB_ENV
124+
- id: doc-kit
125+
subsystem: tools
126+
label: tools
127+
run: |
128+
./tools/dep_updaters/update-doc.sh > temp-output
129+
cat temp-output
130+
tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
131+
rm temp-output
124132
- id: googletest
125133
subsystem: deps
126134
label: dependencies, test

‎Makefile‎

Lines changed: 55 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ V ?= 0
101101
# Use -e to double check in case it's a broken link
102102
available-node = \
103103
if [ -x '$(NODE)' ] && [ -e '$(NODE)' ]; then \
104-
'$(NODE)' $(1); \
104+
PATH='$(PWD)/out/$(BUILDTYPE):$$PATH' '$(NODE)' $(1); \
105105
elif [ -x `command -v node` ] && [ -e `command -v node` ] && [ `command -v node` ]; then \
106106
`command -v node` $(1); \
107107
else \
@@ -340,7 +340,6 @@ coverage-run-js: ## Run JavaScript tests with coverage.
340340
# This does not run tests of third-party libraries inside deps.
341341
test: all ## Run default tests, linters, and build docs.
342342
$(MAKE) -s tooltest
343-
$(MAKE) -s test-doc
344343
$(MAKE) -s build-addons
345344
$(MAKE) -s build-js-native-api-tests
346345
$(MAKE) -s build-node-api-tests
@@ -376,7 +375,7 @@ test-valgrind: all ## Run tests using valgrind.
376375
test-check-deopts: all
377376
$(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --check-deopts parallel sequential
378377

379-
DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md
378+
DOCBUILDSTAMP_PREREQS = doc/api/addons.md
380379

381380
ifeq ($(OSTYPE),aix)
382381
DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
@@ -385,14 +384,22 @@ ifeq ($(OSTYPE),os400)
385384
DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
386385
endif
387386

387+
DOC_KIT ?= tools/doc/node_modules/@nodejs/doc-kit/bin/cli.mjs
388+
388389
node_use_openssl_and_icu = $(call available-node,"-p" \
389390
"process.versions.openssl != undefined && process.versions.icu != undefined")
390391
test/addons/.docbuildstamp: $(DOCBUILDSTAMP_PREREQS) tools/doc/node_modules
391392
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
392393
echo "Skipping .docbuildstamp (no crypto and/or no ICU)"; \
393394
else \
394395
$(RM) -r test/addons/??_*/; \
395-
[ -x '$(NODE)' ] && '$(NODE)' $< || node $< ; \
396+
$(call available-node, \
397+
$(DOC_KIT) generate \
398+
-t addon-verify \
399+
-i doc/api/addons.md \
400+
-o test/addons/ \
401+
--type-map doc/type-map.json \
402+
) \
396403
[ $$? -eq 0 ] && touch $@; \
397404
fi
398405

@@ -791,14 +798,14 @@ test-v8 test-v8-intl test-v8-benchmarks test-v8-all:
791798
$(warning Use the git repo instead: $$ git clone https://github.com/nodejs/node.git)
792799
endif
793800

794-
apidoc_dirs = out/doc out/doc/api out/doc/api/assets
801+
apidoc_dirs = out/doc out/doc/api
795802
skip_apidoc_files = doc/api/quic.md
796803

797804
apidoc_sources = $(filter-out $(skip_apidoc_files), $(wildcard doc/api/*.md))
798805
apidocs_html = $(addprefix out/,$(apidoc_sources:.md=.html))
799806
apidocs_json = $(addprefix out/,$(apidoc_sources:.md=.json))
800807

801-
apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
808+
run-npm-ci = $(PWD)/$(NPM) ci --omit=dev
802809

803810
tools/doc/node_modules: tools/doc/package.json
804811
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
@@ -807,14 +814,12 @@ tools/doc/node_modules: tools/doc/package.json
807814
cd tools/doc && $(call available-node,$(run-npm-ci)) \
808815
fi
809816

817+
RAWVER=$(shell $(PYTHON) tools/getnodeversion.py)
818+
VERSION=v$(RAWVER)
819+
810820
.PHONY: doc-only
811-
doc-only: tools/doc/node_modules \
812-
$(apidoc_dirs) $(apiassets) ## Build the docs with the local or the global Node.js binary.
813-
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
814-
echo "Skipping doc-only (no crypto and/or no ICU)"; \
815-
else \
816-
$(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \
817-
fi
821+
.NOTPARALLEL: doc-only
822+
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.
818823

819824
.PHONY: doc
820825
doc: $(NODE_EXE) doc-only ## Build Node.js, and then build the documentation with the new binary.
@@ -829,82 +834,60 @@ out/doc/api: doc/api
829834
mkdir -p $@
830835
cp -r doc/api out/doc
831836

832-
# If it's a source tarball, assets are already in doc/api/assets
833-
out/doc/api/assets:
834-
mkdir -p $@
835-
if [ -d doc/api/assets ]; then cp -r doc/api/assets out/doc/api; fi;
836-
837-
# If it's not a source tarball, we need to copy assets from doc/api_assets
838-
out/doc/api/assets/%: doc/api_assets/% | out/doc/api/assets
839-
@cp $< $@ ; $(RM) out/doc/api/assets/README.md
840-
841-
842-
run-npm-ci = '$(PWD)/$(NPM)' ci
843-
844-
LINK_DATA = out/doc/apilinks.json
845-
VERSIONS_DATA = out/previous-doc-versions.json
846-
gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION) \
847-
--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api \
848-
--versions-file=$(VERSIONS_DATA)
849-
gen-apilink = tools/doc/apilinks.mjs $(LINK_DATA) $(wildcard lib/*.js)
850-
851-
$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.mjs | out/doc
852-
$(call available-node, $(gen-apilink))
853-
854-
# Regenerate previous versions data if the current version changes
855-
$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.mjs
856-
$(call available-node, tools/doc/versions.mjs $@)
857-
858-
node_use_icu = $(call available-node,"-p" "typeof Intl === 'object'")
859-
860-
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs \
861-
tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs \
862-
tools/doc/apilinks.mjs $(VERSIONS_DATA) | $(LINK_DATA) out/doc/api
863-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
864-
echo "Skipping documentation generation (no ICU)"; \
865-
else \
866-
$(call available-node, $(gen-api)) \
867-
fi
868-
869-
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.mjs \
870-
tools/doc/apilinks.mjs | out/doc/api
871-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
872-
echo "Skipping HTML single-page doc generation (no ICU)"; \
873-
else \
874-
$(call available-node, tools/doc/allhtml.mjs) \
875-
fi
876-
877-
out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api
878-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
879-
echo "Skipping JSON single-file generation (no ICU)"; \
837+
# Generate all doc files (individual and all.html/all.json) in a single doc-kit call
838+
# Using grouped targets (&:) so Make knows one command produces all outputs
839+
ifeq ($(OSTYPE),aix)
840+
# TODO(@nodejs/web-infra): AIX is currently hanging during HTML minification
841+
$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json:
842+
@echo "Skipping $@ (not currently supported by $(OSTYPE) machines)"
843+
else
844+
$(apidocs_html) $(apidocs_json) out/doc/api/all.html out/doc/api/all.json &: $(apidoc_sources) tools/doc/node_modules | out/doc/api
845+
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
846+
echo "Skipping $@ (no crypto and/or no ICU)"; \
880847
else \
881-
$(call available-node, tools/doc/alljson.mjs) \
848+
$(call available-node, \
849+
$(DOC_KIT) generate \
850+
-t legacy-html-all \
851+
-t legacy-json-all \
852+
-i doc/api/*.md \
853+
--ignore $(skip_apidoc_files) \
854+
-o out/doc/api \
855+
-c ./CHANGELOG.md \
856+
-v $(VERSION) \
857+
--index doc/api/index.md \
858+
--type-map doc/type-map.json \
859+
) \
882860
fi
861+
endif
883862

884-
.PHONY: out/doc/api/stability
885-
out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api
886-
@if [ "$(shell $(node_use_icu))" != "true" ]; then \
887-
echo "Skipping stability indicator generation (no ICU)"; \
863+
out/doc/apilinks.json: $(wildcard lib/*.js) tools/doc/node_modules | out/doc
864+
@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
865+
echo "Skipping $@ (no crypto and/or no ICU)"; \
888866
else \
889-
$(call available-node, tools/doc/stability.mjs) \
867+
$(call available-node, \
868+
$(DOC_KIT) generate \
869+
-t api-links \
870+
-i lib/*.js \
871+
-o $(@D) \
872+
-c ./CHANGELOG.md \
873+
-v $(VERSION) \
874+
--type-map doc/type-map.json \
875+
) \
890876
fi
891877

892878
.PHONY: docopen
893-
docopen: out/doc/api/all.html ## Open the documentation in a web browser.
879+
docopen: doc-only ## Open the documentation in a web browser.
894880
@$(PYTHON) -mwebbrowser file://$(abspath $<)
895881

896882
.PHONY: docserve
897-
docserve: $(apidocs_html) $(apiassets) ## Serve the documentation on localhost:8000.
883+
docserve: doc-only ## Serve the documentation on localhost:8000.
898884
@$(PYTHON) -m http.server 8000 --bind 127.0.0.1 --directory out/doc/api
899885

900886
.PHONY: docclean
901887
.NOTPARALLEL: docclean
902888
docclean: ## Remove the generated documentation.
903889
$(RM) -r out/doc
904-
$(RM) "$(VERSIONS_DATA)"
905890

906-
RAWVER=$(shell $(PYTHON) tools/getnodeversion.py)
907-
VERSION=v$(RAWVER)
908891
CHANGELOG=doc/changelogs/CHANGELOG_V$(firstword $(subst ., ,$(RAWVER))).md
909892

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

‎doc/api_assets/README.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

0 commit comments

Comments
 (0)