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 90.14%. Comparing base (a430ef5) to head (09e8384).
Report is 62 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57343      +/-   ##
==========================================
- Coverage   90.22%   90.14%   -0.08%     
==========================================
  Files         635      633       -2     
  Lines      187313   187004     -309     
  Branches    36784    36676     -108     
==========================================
- Hits       168998   168576     -422     
- Misses      11080    11258     +178     
+ Partials     7235     7170      -65     

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

[aduh95]

@avivkeller I can see that, it's in the diff; what's not in the diff is why is it like that, how to fix it, etc.

[flakey5]

Apologizes for the delay, got a bit busy

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

This should be fixed now

I'd also like to get some comment on the performance, here's the command I'm using to measure it:

The old tooling intakes each source file individually, whereas api-docs-tooling intakes all of the files so to only need to bootstrap everything once. This pr does remove caching in the Makefile of the source Markdown files, so running make docclean doc-only -j && time make doc-only -j on the old tooling only generates the docs once whereas with the new tooling it's done twice.

Regardless, the performance isn't amazing and is something we're looking into

[aduh95]

Suggested change

	-c file://$(PWD)/CHANGELOG.md \
	-c $(call available-node, -p 'url.pathToFileURL("CHANGELOG.md")') \

[aduh95]

I wonder if it'd be better to let Make handle the caching and the parallelism – it would also decrease the maintenance burden of maintaining slightly different commands

Suggested change

	$(call available-node, \
	$(NPX) --prefix tools/doc api-docs-tooling generate \
	-t legacy-html-all legacy-json-all api-links \
	-i doc/api/*.md \
	-i lib/*.js \
	--ignore $(skip_apidoc_files) \
	-o out/doc/api/ \
	--no-lint \
	-c file://$(PWD)/CHANGELOG.md \
	-v $(VERSION) \
	-p $(DOC_THREADS) \
	) \
	$(MAKE) $(apidocs_html) $(apidocs_json)

[flakey5]

I'm generally -1 on this since the new tooling is designed to support handling all the files at once, but I'm either or atp. Wdyt @ovflowd?

[ovflowd]

Im not sure what is being requested here, but in general we want to generate all files…. But we should still support users that want to generate just one file or a set of files, not sure if that’s what is being suggested here. Im also not sure parallelism is a good idea 🤔 not sure the old tooling even did that, I don’t think so, but I might be wrong.

[flakey5]

in general we want to generate all files…. But we should still support users that want to generate just one file or a set of files

The current setup allows for this, but the question was more for when we're generating all files, do we want to run the tooling separately for each file vs passing them all into the -i flag

[flakey5]

Hmmm -c $(call available-node, -p 'url.pathToFileURL("CHANGELOG.md")') \ is causing this to be thrown: /bin/sh: 4: Syntax error: "then" unexpected (expecting "fi")

[aduh95]

Hmmm -c $(call available-node, -p 'url.pathToFileURL("CHANGELOG.md")') \ is causing this to be thrown: /bin/sh: 4: Syntax error: "then" unexpected (expecting "fi")

The fix would be to have the tooling take a path rather than a URL

[avivkeller]

We can probably get faster download times if we only install production dependencies

[ovflowd]

Agreed.