doc: list the stability status of each module

[Lxxyx]

Fixes: #23723

Generate a module compatibility table from out/doc/all.json and insert it into documentation.html/md/json.

Preview:

Checklist

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

[mscdex]

I'm not sure something like this is that useful for at least a couple of reasons:

• Users have to know to specifically navigate to the "about this documentation" to see it/know about it. If anything, something like this should probably live in the left sidebar so it's immediately visible, perhaps as a colored icon next to each category name?

• Ultimately assigning a stability to each category is misleading/confusing. What does the stability cover? The existence of the module itself? The entirety of the APIs that live under that category? Something else? For example, the Buffer category is shown here as "Stable", however the category contains several deprecated APIs. Even once we figure out what it should be representing, how do we communicate that clearly and easily to the end user (and is this information particularly useful)?

[Lxxyx]

@mscdex Thank you for your feedback.

1. In the previous issues doc: list the stability status of each API in one place? #23723 (comment), it was decided to put the stability table on the "About this documentation" page. And the stability table helps the developer to choose the right module when using Node.js

2. What is shown here is the stability of the modules. We are not creating a new semantics, just showing it.

3. As for Buffer, the Buffer module has some deprecated methods, but the module is stable (many modules have a similar situation).

[joyeecheung]

LGTM, though @mscdex 's idea of adding icons to the sidebar to indicate stability also sounds good. Any thoughts? @nodejs/documentation

[gireeshpunathil]

some improvements possible (splitting the exact API that is non-stable into separate rows etc) , but thinking more about , it may be difficult to maintain - this is simple and useful as is.

[MylesBorins]

It looks like Modules is not fully covered. There are a variety of APIs that have stability levels including

• commonjs modules
• ES Modules
• various package.json based features (e.g. package exports)
• the module API

I think this goes back to @cjihrig's comment that this isn't entirely accurate for all cases as some modules have methods that are deprecated or experimental.

There is also an inconsistency here between the section title and the API name. fs is in lower case but HTTP is all caps (the module is http). I'd like to see a bit more consistency here.

To be clear, this is great work and I'm mostly pointing out edgecases. I won't block, but it would be nice to see some of these cases worked through

[Lxxyx]

@MylesBorins Thank you for your feedback.

I updated the code so that the section title and API name are now identical and in lowercase.

Preview:

[Trott]

While there will always be ways to improve it and I don't want to discourage those improvements, this is an improvement as it stands and so I'd be fine with landing it, especially since the table is maintained programmatically and so should not be a maintenance annoyance that gets out of synch with other docs.

[MylesBorins]

This is a great iterative improvement. Definitely places to improve, but that will drive more contributions to node!

LGTM

[Trott]

dgram is showing up in an unexpected place in the table (because it's being ordered as udp I guess). Not a blocking comment. This can land. But if it's easy enough to fix, let's do that.

[Lxxyx]

dgram is showing up in an unexpected place in the table (because it's being ordered as udp I guess). Not a blocking comment. This can land. But if it's easy enough to fix, let's do that.

Thanks for the reply, the problem has been fixed.

Preview

[aduh95]

Apologies, my suggestion was flawed – we need to specify the position, otherwise it sometimes jump to the end of the file.

[nodejs-github-bot]

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

[aduh95]

Landed in 2bb42bf