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.56%. Comparing base (768f3ba) to head (88544ae).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #57343   +/-   ##
=======================================
  Coverage   88.56%   88.56%           
=======================================
  Files         703      703           
  Lines      208291   208291           
  Branches    40169    40175    +6     
=======================================
+ Hits       184472   184482   +10     
- Misses      15831    15833    +2     
+ Partials     7988     7976   -12     

see 32 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]

cc @aduh95 anything else needed?

[aduh95]

It looks like the generated JSON files are very different from the one generated by the existing tool. IMO we should have assert.partialDeepStrictEqual(JSON.parse(fileOnThisBranch), JSON.parse(sameFileOnMain)), otherwise it would be a breaking change for users who consume those JSON files. Maybe an option would be keep the existing tooling for JSON files, so it doesn't block this PR?
Other than that, the HTML part LGTM (although the time it takes to generate is still a notable regression, but not a blocker).

[ovflowd]

It looks like the generated JSON files are very different from the one generated by the existing tool. IMO we should have assert.partialDeepStrictEqual(JSON.parse(fileOnThisBranch), JSON.parse(sameFileOnMain)), otherwise it would be a breaking change for users who consume those JSON files. Maybe an option would be keep the existing tooling for JSON files, so it doesn't block this PR?

The JSON output is supposed to be an 1:1 match in terms of structure. We already validated this format with @targos and many others in the past. Can you please point out on what is different?

Other than that, the HTML part LGTM (although the time it takes to generate is still a notable regression, but not a blocker).

As mentioned, that is only on the legacy generator. The one with the redesign is much faster.

[aduh95]

The JSON output is supposed to be an 1:1 match in terms of structure

Well it's not; for example, domain.json#modules[0].meta looks like this on main:

      "meta": {
        "deprecated": [
          "v1.4.2"
        ],
        "changes": [
          {
            "version": "v8.8.0",
            "pr-url": "https://github.com/nodejs/node/pull/15695",
            "description": "Any `Promise`s created in VM contexts no longer have a `.domain` property. Their handlers are still executed in the proper domain, however, and `Promise`s created in the main context still possess a `.domain` property."
          },
          {
            "version": "v8.0.0",
            "pr-url": "https://github.com/nodejs/node/pull/12489",
            "description": "Handlers for `Promise`s are now invoked in the domain in which the first promise of a chain was created."
          }
        ]
      },

It looks like this on this PR:

            "meta": [
                {
                    "changes": [
                        {
                            "version": "v8.0.0",
                            "pr-url": "https://github.com/nodejs/node/pull/12489",
                            "description": "Handlers for `Promise`s are now invoked in the domain in which the first promise of a chain was created."
                        },
                        {
                            "version": "v8.8.0",
                            "pr-url": "https://github.com/nodejs/node/pull/15695",
                            "description": "Any `Promise`s created in VM contexts no longer have a `.domain` property. Their handlers are still executed in the proper domain, however, and `Promise`s created in the main context still possess a `.domain` property."
                        }
                    ],
                    "added": [],
                    "napiVersion": [],
                    "deprecated": [
                        "v1.4.2"
                    ],
                    "removed": []
                },
                {
                    "changes": [],
                    "added": [],
                    "napiVersion": [],
                    "deprecated": [],
                    "removed": []
                },
                {
                    "changes": [],
                    "added": [],
                    "napiVersion": [],
                    "deprecated": [],
                    "removed": []
                },
                {
                    "changes": [],
                    "added": [],
                    "napiVersion": [],
                    "deprecated": [],
                    "removed": []
                },
                {
                    "changes": [],
                    "added": [],
                    "napiVersion": [],
                    "deprecated": [],
                    "removed": []
                }
            ],

I don't mind the fact that the more keys are present, however it's weird that it's now an array and has additional empty entries.

In globals.json, we have a bunch on empty keys in this PR:

    "introduced_in": [],
    "stability": [],
    "stabilityText": [],
    "shortDesc": [],
    "classes": []

On main, those are not empty:

  "introduced_in": "v0.10.0",
  "stability": 2,
  "stabilityText": "Stable",
  "classes": [
    {
       …

I verified with the GHA-generated files in https://github.com/nodejs/node/actions/runs/19650553861?pr=57343 in case it was something wrong with my local repo, but no I see the same discrepancies.

[ovflowd]

That actually sounds like a bug. I wonder if it is a regression. On early days of the doc-kit the JSON was fully compliant with main, I even remember doing tests with @flakey5 and @targos in-person at NodeConf but I might be misremembering things.

Since many changes have happened in between, things could have slipped.

Since we want to initially bring doc-kit to be fully compliant with the current state of the existing tooling before we move to the new JSON format and generated pages, I do feel these need to be fixed.

cc @avivkeller / @araujogui and @flakey5 any ideas?

[avivkeller]

I have a strong feeling that it’s from https://github.com/nodejs/doc-kit/blob/main/src/generators/legacy-json/utils/buildSection.mjs#L19, as we wanted to standardize the types (ie always make these things arrays, and not sometimes arrays, other times strings, and sometimes undefined)