doc: list the stability status of each API in one place?

[joyeecheung]

Right now each API has their own page with their stability index, but AFAIK there is not a central place where you can find the stability status of all the APIs at a glance (correct me if I am wrong). It may be useful to have a list somewhere in https://github.com/nodejs/node/blob/master/doc/api/documentation.md#stability-index

[robertoschiavone]

I can pick this one

[hyeonQ]

I expect to make the first commit of nodejs. I can gather the stability of APIs in one place.

[vsemozhetbyt]

I suppose we may need to automate this with doc tools scripts. Otherwise, each deprecation and API addition will need to be addressed in this list manually which may be error-prone.

[joyeecheung]

I suppose we may need to automate this with doc tools scripts.

@vsemozhetbyt Good idea. Can you leave a few pointers? I only have a vague idea that people who want to hack on this should start in https://github.com/nodejs/node/tree/master/tools/doc

Also cc @nodejs/documentation

[vsemozhetbyt]

Recently, we change our toolchain a bit, so maybe @rubys can give some hints.

I think we have at least two options:

1. Parse TOC in all.html. TOC entries already have class="stability_*" attributes for deprecated and experimental stability. But we may need to distinguish API headers from other headers here (by a RegExp?).

2. Parse all.json. It will be easier to distinguish API entries from other entries there (look for "classes", "methods", and "properties" fields), and the field "stability" also exists there.

[rubys]

I recommend that all.json approach. The input data is already parsed. Iterate over the structure, producing output as you go. The tool should go in the tools/doc/ directory, and added to the Makefile as depending on out/doc/api/all.json. As we seem to have volunteer(s), I'll review and coach as needed.

[hyeonQ]

I hope to try this work.
So far as I understand it, there is a need to gather the stability of the various APIs of node.js and It is a better to parse all.json.
By the way, I am confused which files need to be modified and where to put gathered things

[huhgawz]

@HYU-LeeHG are you actively working on this issue? If not, it would be great to take it

[shobhitchittora]

@rubys I went ahead wrote a script to get all the stability keys from the json mentioned.

API	Stability
assert	(2) Stable
async_hooks	(1) Experimental
buffer	(2) Stable
cluster	(2) Stable
console	(2) Stable
crypto	(2) Stable
dns	(2) Stable
dns_promises_api	(1) Experimental
Events	(2) Stable
fs	(2) Stable
fs_promises_api	(1) Experimental
http	(2) Stable
http/2	(1) Experimental
https	(2) Stable
inspector	(1) Experimental
module	(2) Stable
os	(2) Stable
path	(2) Stable
performance_timing_api	(1) Experimental
querystring	(2) Stable
readline	(2) Stable
repl	(2) Stable
stream	(2) Stable
string_decoder	(2) Stable
timers	(2) Stable
tls_(ssl)	(2) Stable
trace_events	(1) Experimental
tty	(2) Stable
dgram	(2) Stable
url	(2) Stable
util	(2) Stable
serialization_api	(1) Experimental
vm	(2) Stable
vm.SourceTextModule	(1) Experimental
worker_threads	(1) Experimental
zlib	(2) Stable

What are your thoughts on organizing this? What can be the next steps?

[adarshsaraogi]

can i take this issue

[shuhei]

Hi, I was looking for a good first issue and ran into this issue.

So shobhitchittora@b0c5461 by @shobhitchittora already collects stability statuses and outputs them into a table. The problem is how to put it into the docs. Possible options would be:

1. Output the table as a separate file like out/doc/api/stability_index.md (also .html and .json?) with the tool, and have a link to the file from doc/api/documentation.md
2. Insert the table into out/doc/api/documentations.md, .html and .json with the tool
3. Update doc/api/documentation.md with the tool and commit the change into git

The option 1 seems easiest to me. What do you think? @joyeecheung @rubys @shobhitchittora

[joyeecheung]

@shuhei I'd prefer we do option 2 if possible, but we could also implement option 1 first (in any cases I can imagine a stability.json hosted on our website being useful for consumers)

[RamirezAlex]

If no one is working on it I can give it a try.