tools: build doc/api/all.html by combining generated HTML

[rubys]

Combine the toc and api contents from the generated doc/api/*.html
files. This ensures that the single page version of the documentation
exactly matches the individual pages.

Fixes#20100

This pull request differs from #21544 in that it is implemented using regular expressions and has no dependencies. See #21544 (comment) for more context.

If this pull request is merged, the other will be deleted.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[Trott]

@TimothyGu@vsemozhetbyt

[Trott]

@nodejs/documentation It would be a good idea for someone to build all.html with this and compare it to what's in master. The diff should show some broken links being fixed but otherwise there should be no significant changes.

[rubys]

I've made a few fixes to reduce the differences, rebased to master, and here is a current set of differences: https://gist.github.com/rubys/bae70ed087efec625ac04823aaaf803e

Summary:

• title is different; instead of picking the first title the new title is the part that is common to all titles. This could be changed, but I would still not recommend that it be the first title.
• Some whitespace changes - nothing that would affect rendering
• No include comments; something like that could be added if required, but likely would differ in that it would make more sense to reference the generated html files instead of the md source.
• An odd change in api stability section; for reasons I don't understand the generation of this section added links previously. Links that are not present on the documentation page. Compare the current node documentation as published publicly: all.html vs documentation.html.
• The previously generated all.html would sometimes link to definitions within the all.html page, and other times link to definitions on the separate page, and sometimes link to the wrong thing entirely. This has been changed to always link within the same page, and always to exactly what was linked to in the separate pages.

[vsemozhetbyt]

The same results here)

An odd change in api stability section...

This is OK. Due to this code:

node/tools/doc/html.js

Lines 209 to 216 in 1bf42f4

	// Do not link to the section we are already in.
	constnoLinking=filename==='documentation'&&
	heading!==null&&heading.text==='Stability Index';
	token.text=`<div class="api_stability api_stability_${number}">`+
	(noLinking ? '' :
	'<a href="documentation.html#documentation_stability_index">')+
	`${prefix}${number}${noLinking ? '' : '</a>'}${explication}</div>`
	.replace(/\n/g,' ');

these links were skipped in documentation.html but wrongly reappeared in all.html. The new result is more consistent, I think.

[vsemozhetbyt]

Nit: extra space before "As".

[vsemozhetbyt]

clean -> Clean ?

[vsemozhetbyt]

contenated -> concatenated?

[rubys]

Can somebody spot the CI error for me? I don't see it. I searched for 'error' and 'fail'.

[vsemozhetbyt]

You can also search for "not ok" in raw log: https://api.travis-ci.com/v3/job/132202841/log.txt
The test failure seems unrelated:
not ok 2146 es-module/test-esm-loader-invalid-format

[vsemozhetbyt]

Full CI: https://ci.nodejs.org/job/node-test-pull-request/15681/

[vsemozhetbyt]

Refs: #21605

[vsemozhetbyt]

#21605 is landed.
New full CI: https://ci.nodejs.org/job/node-test-pull-request/15684/

[Trott]

And again... CI: https://ci.nodejs.org/job/node-test-pull-request/15695/

[vsemozhetbyt]

I shall land in some hours if there are no objections.

[vsemozhetbyt]

Landed in f85962f
Thank you!

[vsemozhetbyt]

Maybe we can do the same for the all.json so that we could completely rid of all.md. This can be done by JSON.parse() + combine new object + JSON.stringify() or just manually concatenate the new stringified serialization, not sure what would be easier or more effective. This may be semver-major as it may change the JSON structure users rely on programmatically.

[rubys]

@vsemozhetbyt in the process, we could also get rid of preprocess.js and therefore processIncludes. Please open an issue and I'll work on a pull request.

[vsemozhetbyt]

We usually do not require an issue for a PR. Feel free to pace as you feel comfortable)

[Trott]

Awesome to see "Contributor" on @rubys's comments etc. everywhere now. 🎉