build, doc: use new api doc tooling #57343

flakey5 · 2025-03-06T06:23:57Z

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

~~Currently a draft just to get feedback on the approach to this integration.~~

cc @nodejs/web-infra

nodejs-github-bot · 2025-03-06T06:24:02Z

Review requested:

@nodejs/nodejs-website
@nodejs/web-infra

Makefile

vcbuild.bat

tools/doc/README.md

ovflowd

@flakey5 I guess you also need to check our GitHub Action Workflows, and also other mentions of these files within the source.

Like within the Contributor Docs, there is a file that describes how the legacy API doc tooling works, and I believe there are other references also.

flakey5 · 2025-03-10T22:21:09Z

lint-js-and-md is failing because of the linting errors since it exits with a non-zero status code if there's anything wrong with the docs. I think we should skip the REPLACEME checks for normal ci runs.

It also looks like synopsis.md fails the introduced_in check because it's not under the top-level header, should it be enforced that introduced_in goes under the top-level header or should we change it to just check that it exists somewhere in the file (like it was doing previously)?

flakey5 · 2025-03-10T22:34:35Z

Also not sure what's going on with lint-addon-docs? cc @araujogui

ovflowd · 2025-03-10T22:38:04Z

lint-js-and-md is failing because of the linting errors since it exits with a non-zero status code if there's anything wrong with the docs. I think we should skip the REPLACEME checks for normal ci runs.

It also looks like synopsis.md fails the introduced_in check because it's not under the top-level header, should it be enforced that introduced_in goes under the top-level header or should we change it to just check that it exists somewhere in the file (like it was doing previously)?

REPLACEME shouldn't error, imo, just give a warning. Our linter should have warn and error levels.

And yes introduced_in must be top level!

codecov · 2025-03-10T23:53:32Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.14%. Comparing base (a6d3585) to head (2ecd61f).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57343      +/-   ##
==========================================
- Coverage   90.23%   90.14%   -0.10%     
==========================================
  Files         630      628       -2     
  Lines      185129   184619     -510     
  Branches    36234    36079     -155     
==========================================
- Hits       167049   166420     -629     
- Misses      11037    11211     +174     
+ Partials     7043     6988      -55

see 47 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Makefile

araujogui · 2025-03-11T01:49:00Z

lint-js-and-md is failing because of the linting errors since it exits with a non-zero status code if there's anything wrong with the docs. I think we should skip the REPLACEME checks for normal ci runs.

It also looks like synopsis.md fails the introduced_in check because it's not under the top-level header, should it be enforced that introduced_in goes under the top-level header or should we change it to just check that it exists somewhere in the file (like it was doing previously)?

Actually, the linter only returns 1 if there's an error-level issue, and I don't think that's the case here.

araujogui · 2025-03-11T01:49:50Z

Also not sure what's going on with lint-addon-docs? cc @araujogui

I’m not sure either, but I’ll check it out.

ovflowd · 2025-03-12T10:26:58Z

@flakey5:

3:1-3:9   warning Use "the Node.js" instead of "Node.js'" prohibited-strings remark-lint
4:46-4:50 warning Use "Node.js" instead of "Node"         prohibited-strings remark-lint

On the README.md file you updated (tools/doc/README.md) after updating those can you run make format-md (?)

Makefile

ovflowd

This is the result of many months of arduous work between many awesome folks, including @flakey5 @AugustinMauroy @araujogui @ovflowd @avivkeller and others.

I'm so proud of what we are achieving here and this is a huge step towards a modern tooling and a revamped API docs within Node.js

Approving, as I believe this is ready!

ovflowd · 2025-03-13T17:24:16Z

cc @nodejs/collaborators can we have another approval here? 🙏

lpinca

RSLGTM because it is hard to review and outside of my comfort zone.

avivkeller · 2025-03-24T20:30:21Z

Hey everyone,

The Website and Web-Infra teams have been looking into an issue where GitHub Actions seemed to report incorrect line numbers for REPLACEME (and other invalid versions) in the linter. At first, it looked like the errors weren’t lining up, and even files without REPLACEME comments were flagged. But after digging in, we realized the issue wasn’t with the reporting.

Since Actions use a merge commit, the reported line numbers were actually correct in the main branch. The mismatch happened because the PR’s head branch was outdated—it didn’t have that merge commit, so it had older versions of the files. That made it look like the errors were in the wrong place. Once we updated the branch, everything lined up correctly, and the errors disappeared. That also explains why we couldn’t reproduce it locally—our branches didn’t include the merge commit.

For more information on our investigation into this, please see this Slack thread.

In short: everything was working fine; the GitHub UI's use of the outdated branch when showing flagged files just made it seem like it wasn’t.

aduh95 · 2025-03-24T21:03:05Z

In short: everything was working fine

How is it working fine if it reports REPLACEME as an invalid version?

ovflowd · 2025-03-24T21:05:25Z

In short: everything was working fine

How is it working fine if it reports REPLACEME as an invalid version?

Apparently GitHub shows the file contents from files on the parent branch. So if the PR branch is out of sync with main, the api-docs-tooling is correctly reporting the files, but the GitHub PR diff is showing the files from main (Maybe my words are not explaining it correctly, @avivkeller can you explain better?)

ovflowd · 2025-03-24T21:06:44Z

The branch got rebased and it seems to be correctly saying which YAML blocks have errors. Although, cc @araujogui it'd be good if it shown the exact line within the YAML.

aduh95 · 2025-03-24T21:14:40Z

I mean, not showing the correct line is indeed something we should try to fix (but IMO not blocking). However, I think a more problematic behavior is to report REPLACEME as an invalid version, I think that should be blocking as it will nudge contributors to not follow our process. (also it doesn't seem to treat an invalid version as hard failure, which is a regression)

avivkeller · 2025-03-24T21:15:18Z

How is it working fine if it reports REPLACEME as an invalid version?

Currently, we have it setup to report REPLACEME as an invalid version. While this behavior can be modified in the future, I don't is consider it an issue with the linter at the moment because it is a deliberate decision.

Apparently GitHub shows the file contents from files on the parent branch. So if the PR branch is out of sync with main, the api-docs-tooling is correctly reporting the files, but the GitHub PR diff is showing the files from main (Maybe my words are not explaining it correctly, @avivkeller can you explain better?)

GitHub's behavior during a pull request (PR) process can cause discrepancies between what api-docs-tooling reports and what the GitHub PR diff displays.

Here’s what happens:

On the pull_request Actions trigger, github.ref is set to refs/pull/PULL_REQUEST_NUMBER/merge.
When actions/checkout retrieves this ref, it checks out this version of the repository, which is already rebased with main.
As a result, api-docs-tooling correctly reports linting errors from the rebased version (which includes changes from main).

However, the GitHub PR diff operates differently:

It takes the information from the merged version (the rebase with main) but applies it to the PR head ref (the version of the branch before the merge).
This discrepancy causes the confusion because the PR diff shows the flagged data from main on the PR head ref's files.

tools/doc/package.json

ovflowd · 2025-03-24T21:28:50Z

I mean, not showing the correct line is indeed something we should try to fix (but IMO not blocking). However, I think a more problematic behavior is to report REPLACEME as an invalid version, I think that should be blocking as it will nudge contributors to not follow our process. (also it doesn't seem to treat an invalid version as hard failure, which is a regression)

We treat REPLACEME as a warning, not an error. More to create a nudge to remind contributors to eventually change the REPLACEME to a version.

avivkeller · 2025-03-24T22:11:06Z

Tests are failing due to nodejs/api-docs-tooling#228, however this function should be exported from node:fs in the generated node executable. I can revert the PR if needed, but I don't think this error should've occured:(https://github.com/nodejs/node/actions/runs/14044808144/job/39323129311?pr=57343#step:11:5337

Edit: Reverting @ nodejs/api-docs-tooling#237

ovflowd · 2025-03-24T22:12:28Z

Tests are failing due to nodejs/api-docs-tooling#228, however this function should be exported from node:fs in the generated node executable. I can revert the PR if needed, but I don't think this error should've occured:(https://github.com/nodejs/node/actions/runs/14044808144/job/39323129311?pr=57343#step:11:5337

The CI seems to be using Node v20, not sure if intentional.

ovflowd · 2025-03-24T22:14:29Z

But FWIW @avivkeller let’s not use experimental features on the api doc tooling. Add the glob package back and lets just stay on the safe side :)

aduh95

Issues that need to be addressed:

We should keep the existing tests (at least for now, can be removed in a follow up).
We should not report REPLACEME as an invalid version.
We should report invalid versions as a hard failure.
It pretends it generates the docs for Node.js 22.14.0 instead of 24.0.0 🤨
make: *** No rule to make target 'out/doc/api/index.html'

There are some weird inconsistencies with the current docs, e.g. About this documentation and Usage and example are listed on a stand alone section in current nav menu, with this PR it's in the middle of the other pages. It uses Added In instead of Added in. It seems there have been a lot of (arguably small) decisions that were made. It'd be useful to have a list.

aduh95 · 2025-03-24T22:38:44Z

More to create a nudge to remind contributors to eventually change the REPLACEME to a version.

Contributors should never change REPLACEME to a version

jasnell · 2025-03-24T22:43:38Z

For background, the REPLACEME tokens are replaced by the releasers when a release is actually being put together.

ovflowd · 2025-03-24T22:43:49Z

There are some weird inconsistencies with the current docs, e.g. About this documentation and Usage and example are listed on a stand alone section in current nav menu, with this PR it's in the middle of the other pages. It uses Added In instead of Added in. It seems there have been a lot of (arguably small) decisions that were made

Those were already talked over when we were introducing the legacy-html generators on api-docs-tooling and we had the TSC chiming in and giving a 👍 ; I recall @targos provided a lot of good feedback when we introduced these generators.

So intentionally, the new tooling is not providing an exact 1:1 match. But functionally it is an 1:1 match. We did deep comparisons between the HTML and contents. (But yes, there are some minor differences)

ovflowd · 2025-03-24T22:44:35Z

For background, the REPLACEME tokens are replaced by the releasers when a release is actually being put together.

That’s what I meant when I said contributors. Apologies for the poor explanation from my side!

ovflowd · 2025-03-24T22:45:31Z

We should not report REPLACEME as an invalid version.

I recall there was a request from someone that we reported on that so that no one forgets to accidentally make a release without replacing all REPLACEME.

ovflowd · 2025-03-24T22:47:06Z

It pretends it generates the docs for Node.js 22.14.0 instead of 24.0.0 🤨

Odd, it should be getting the version from the process variable. Running locally on main it gives me 24.0.0 (or something similar, gotta double check)

avivkeller · 2025-03-24T22:49:08Z

Probably b/c you are using the built node executable, whereas this is building from v22.14.0 (Github Actions uses the latest LTS).

aduh95 · 2025-03-24T22:55:06Z

I recall there was a request from someone that we reported on that so that no one forgets to accidentally make a release without replacing all REPLACEME.

There are already checks for that, added in #24575:

node/Makefile

Lines 1072 to 1078 in 1a6bef2

    
           release-only: check-xz ## Prepare Node.js for release. 
        
           	@if [ "$(DISTTYPE)" = "release" ] && `grep -q REPLACEME doc/api/*.md`; then \ 
        
           		echo 'Please update REPLACEME tags in the following doc/api/*.md files (See doc/contributing/releases.md):\n' ; \ 
        
           		REPLACEMES="$(shell grep -l REPLACEME doc/api/*.md)" ; \ 
        
           		echo "$$REPLACEMES\n" | tr " " "\n" ; \ 
        
           		exit 1 ; \ 
        
           	fi

Switches over to using the new doc generation tooling. For more background on this, please see nodejs#52343 Signed-off-by: flakey5 <73616808+flakey5@users.noreply.github.com> Co-authored-by: Claudio W <cwunder@gnome.org>

flakey5 · 2025-03-25T15:45:11Z

make: *** No rule to make target 'out/doc/api/index.html'

Where was this seen?

avivkeller · 2025-03-28T15:42:55Z

We should not report REPLACEME as an invalid version.

We should report invalid versions as a hard failure.

This has been addressed :-)

It pretends it generates the docs for Node.js 22.14.0 instead of 24.0.0 🤨

This can probably be solved by explicitly passing the version of Node.js we are trying to generate to the new tooling. IIRC there should be some parsing logic in the Makefile. (I think it's

node/Makefile

Line 895 in ca74d64

VERSION=v$(RAWVER)

)

aduh95 · 2025-03-28T16:45:58Z

make: *** No rule to make target 'out/doc/api/index.html'

Where was this seen?

If you run make out/doc/api/index.html from the root of the repo, it works without this PR, it fails with it. The actual issue being that if we were to merge this, https://nodejs.org/api/index.html would be 404.

ovflowd · 2025-03-28T16:53:58Z

make: *** No rule to make target 'out/doc/api/index.html'

Where was this seen?

If you run make out/doc/api/index.html from the root of the repo, it works without this PR, it fails with it. The actual issue being that if we were to merge this, https://nodejs.org/api/index.html would be 404.

@flakey5 have you restored index.md?

avivkeller · 2025-03-28T16:57:32Z

Makefile

-
-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 \


FWIW It's B/C this part was removed

nodejs-github-bot added build doc needs-ci tools windows labels Mar 6, 2025

flakey5 marked this pull request as draft March 6, 2025 06:24

flakey5 force-pushed the flakey5/20250305/api-docs-tooling branch from 77ede22 to 3423c21 Compare March 6, 2025 06:29

flakey5 commented Mar 6, 2025

View reviewed changes

Makefile Outdated Show resolved Hide resolved

flakey5 commented Mar 6, 2025

View reviewed changes

vcbuild.bat Outdated Show resolved Hide resolved

flakey5 force-pushed the flakey5/20250305/api-docs-tooling branch from 3423c21 to 451f8a7 Compare March 6, 2025 06:31

flakey5 commented Mar 6, 2025

View reviewed changes

tools/doc/README.md Show resolved Hide resolved

ovflowd reviewed Mar 6, 2025

View reviewed changes

flakey5 force-pushed the flakey5/20250305/api-docs-tooling branch 3 times, most recently from cf2609b to a3ce99d Compare March 10, 2025 22:04

flakey5 marked this pull request as ready for review March 10, 2025 22:05

araujogui reviewed Mar 11, 2025

View reviewed changes

Makefile Outdated Show resolved Hide resolved

araujogui mentioned this pull request Mar 11, 2025

fix(addon-verify): await files writing nodejs/api-docs-tooling#207

Merged

2 tasks

ovflowd reviewed Mar 13, 2025

View reviewed changes

Makefile Outdated Show resolved Hide resolved

ovflowd approved these changes Mar 13, 2025

View reviewed changes

lpinca approved these changes Mar 13, 2025

View reviewed changes

flakey5 force-pushed the flakey5/20250305/api-docs-tooling branch from 69bef76 to dd55609 Compare March 24, 2025 19:12

bjohansebas approved these changes Mar 24, 2025

View reviewed changes

aduh95 reviewed Mar 24, 2025

View reviewed changes

tools/doc/package.json Outdated Show resolved Hide resolved

aduh95 requested changes Mar 24, 2025

View reviewed changes

avivkeller mentioned this pull request Mar 24, 2025

chore(lint): report error on invalid change versions, except REPLACEME nodejs/api-docs-tooling#238

Merged

build, doc: use new api doc tooling

2ecd61f

Switches over to using the new doc generation tooling. For more background on this, please see nodejs#52343 Signed-off-by: flakey5 <73616808+flakey5@users.noreply.github.com> Co-authored-by: Claudio W <cwunder@gnome.org>

flakey5 force-pushed the flakey5/20250305/api-docs-tooling branch from ef6e54e to 2ecd61f Compare March 25, 2025 15:44

avivkeller reviewed Mar 28, 2025

View reviewed changes


		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 \

build, doc: use new api doc tooling #57343

Are you sure you want to change the base?

build, doc: use new api doc tooling #57343

Conversation

flakey5 commented Mar 6, 2025 • edited Loading

nodejs-github-bot commented Mar 6, 2025

ovflowd left a comment

Choose a reason for hiding this comment

flakey5 commented Mar 10, 2025 • edited Loading

flakey5 commented Mar 10, 2025

ovflowd commented Mar 10, 2025

codecov bot commented Mar 10, 2025 • edited Loading

Codecov Report

araujogui commented Mar 11, 2025

araujogui commented Mar 11, 2025

ovflowd commented Mar 12, 2025

ovflowd left a comment

Choose a reason for hiding this comment

ovflowd commented Mar 13, 2025

lpinca left a comment • edited Loading

Choose a reason for hiding this comment

avivkeller commented Mar 24, 2025 • edited Loading

aduh95 commented Mar 24, 2025

ovflowd commented Mar 24, 2025

ovflowd commented Mar 24, 2025

aduh95 commented Mar 24, 2025 • edited Loading

avivkeller commented Mar 24, 2025 • edited Loading

ovflowd commented Mar 24, 2025

avivkeller commented Mar 24, 2025 • edited Loading

ovflowd commented Mar 24, 2025

ovflowd commented Mar 24, 2025

aduh95 left a comment • edited Loading

Choose a reason for hiding this comment

aduh95 commented Mar 24, 2025

jasnell commented Mar 24, 2025

ovflowd commented Mar 24, 2025

ovflowd commented Mar 24, 2025

ovflowd commented Mar 24, 2025

ovflowd commented Mar 24, 2025

avivkeller commented Mar 24, 2025 • edited Loading

aduh95 commented Mar 24, 2025

flakey5 commented Mar 25, 2025

avivkeller commented Mar 28, 2025

aduh95 commented Mar 28, 2025

ovflowd commented Mar 28, 2025

avivkeller Mar 28, 2025

Choose a reason for hiding this comment

flakey5 commented Mar 6, 2025 •

edited

Loading

flakey5 commented Mar 10, 2025 •

edited

Loading

codecov bot commented Mar 10, 2025 •

edited

Loading

lpinca left a comment •

edited

Loading

avivkeller commented Mar 24, 2025 •

edited

Loading

aduh95 commented Mar 24, 2025 •

edited

Loading

avivkeller commented Mar 24, 2025 •

edited

Loading

avivkeller commented Mar 24, 2025 •

edited

Loading

aduh95 left a comment •

edited

Loading

avivkeller commented Mar 24, 2025 •

edited

Loading