Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit e55edde

Browse filesBrowse files
flakey5ovflowdavivkelleraduh95joyeecheung
authored 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
Copy full SHA for e55edde

58 files changed

+4,552-5,579Lines changed: 4552 additions & 5579 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Dismiss banner
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎.github/CODEOWNERS‎

Copy file name to clipboardExpand all lines: .github/CODEOWNERS
-2Lines 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
Collapse file

‎.github/workflows/tools.yml‎

Copy file name to clipboardExpand all lines: .github/workflows/tools.yml
+8Lines 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
Collapse file

‎Makefile‎

Copy file name to clipboardExpand all lines: Makefile
+55-72Lines 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
Collapse file

‎doc/api_assets/README.md‎

Copy file name to clipboardExpand all lines: doc/api_assets/README.md
-7Lines changed: 0 additions & 7 deletions
This file was deleted.

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.