build, doc: use new api doc tooling

[flakey5]

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]

Review requested:

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

[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]

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]

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

[ovflowd]

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]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.51%. Comparing base (a1f421f) to head (c318315).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57343      +/-   ##
==========================================
- Coverage   88.52%   88.51%   -0.01%     
==========================================
  Files         703      703              
  Lines      208506   208538      +32     
  Branches    40213    40218       +5     
==========================================
+ Hits       184570   184596      +26     
+ Misses      15953    15952       -1     
- Partials     7983     7990       +7     

see 37 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.

[araujogui]

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]

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]

@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 (?)

[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]

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

[lpinca]

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

[ovflowd]

@ovflowd https://github.com/nodejs/node/actions/runs/20132866469/job/57778501011?pr=57343#step:7:18

Yes? I literally posted that on Slack.

[ovflowd]

@ovflowd nodejs/node/actions/runs/20132866469/job/57778501011?pr=57343#step:7:18

Yes? I literally posted that on Slack.

Fixed by nodejs/doc-kit#516

[avivkeller]

Bump @aduh95, we are pretty hopeful that all of your concerns should be resolved :-)

[ovflowd]

Bump @aduh95, we are pretty hopeful that all of your concerns should be resolved :-)

Yeah, we added comparison right now, but I also believe the JSON should be correct.

[ovflowd]

But for the sake of checking it, @avivkeller can you compare both and see what you find as diff? (Some fields are expected to be slightly different, such as desc etc)

[avivkeller]

As of this comment, the diff is available at https://gist.github.com/avivkeller/6bcb5fc17d72a3bed77744d4094949bd (after nodejs/doc-kit#524 lands)

[avivkeller]

@ovflowd can you bump the doc-kit version to the latest version?

@aduh95 can you re-review? The JSON format should be stable, and decently similar to the old format, with slightly different HTML output (md to html differences), and more accurate parameter parsing.

Any little kinks and quirks can also be worked out, and I'm going to do a full read through of the diff today.

[aduh95]

I'd like to work on adding some tests to validate the JSON structure, it's on my list of things to do but I haven't come to it yet