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

Checklist

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

[Trott]

/ping @nodejs/documentation especially @vsemozhetbyt

[Trott]

I added two commits, one to update package-lock.json (and add a missing dependency or two apparently) and another to update the LICENSE file. Those commits can be squashed out upon landing (or sooner).

[vsemozhetbyt]

I'll try to review this PR and #21490 this week, but I am not sure how thoroughly I will be able to do this: I have much less time recently and this is a whole new module set I am not experienced with. So if anybody knows this toolchain well, please, chime in)

[Trott]

The title of the all.html doc ends up being different. On master:

  <title>About this Documentation | Node.js v11.0.0 Documentation</title>

On this branch:

  <title>Node.js v11.0.0 Documentation</title>

For some reason, the links in the doc-version-picker are different (all.html vs. _toc.html).

[rubys]

A brief overview of JSDOM: it is a faithful implementation of the browser DOM. So if anybody here has experience writing JavaScript in the browser, this should look very familiar. I said the overview would brief. :-)

As to doc-version-picker lnks: good catch! I've pushed a fix. Take a look at that fix to get an idea of what I mean by this code should look very familiar to anybody who has experience writing javascript in the browser.

As to the title: that change is intentional, though perhaps it could be improved. Previously, all.html was produced by concatenating the markdown input and running it through the publishing pipeline. For the table of contents and api content, this produced mostly the desirable results (with a few bugs as noted in this issue). In the case of the title, instead of concatenating the titles of each of the 50 documents, it picked the title of the first document.

Instead I went with the part of the title that is common to all documents. A good case could be made that this should be prefixed by something indicating 'single page'. Suggestions welcome. In any case, this would be a one line change - search for title.textContent =.

[jasnell]

First off. Hi @rubys! Great to see you here! It's been quite a while, my friend!

Second, great to see work here. I won't be able to do a review until later this week.

[rubys]

Hi @jasnell! It hasn't really been that long. Looking forward to working with you again.

[TimothyGu]

Hi, this PR is great. However, as one of the maintainers of jsdom I'm reluctant to recommend the inclusion of the entire package in Node.js tree, just because of its sheer size. I'd like to explore any possible alternatives that would allow us to accomplish the same goal in a more efficient way.

Moreover, as I noted in #21490 (comment), it seems like we would be duplicating a lot of npm modules we already include in the code base, like acorn. I know this is already somewhat an issue with npm and ESLint in tree, but it would be awesome if we could dedupe a bit (especially with ESLint, which is also in the tools directory).

[rubys]

@TimothyGu Perhaps you would prefer a version based on RegExps? Something like https://gist.github.com/rubys/26fb5b75d624098b021575c4b58874b0 perhaps? Much faster, zero dependencies, but perhaps a little less robust in that it depends on a number of HTML serialization choices; but overall that's probably acceptable for a tool that is only used at build time.

[TimothyGu]

@rubys Yeah, I think that’s a better choice.

[jasnell]

Zero dependencies is much better, even if a bit less robust.

[rubys]

Alternate version of this pull request, with zero dependencies can be found here: #21568

[rubys]

Closing as #21568 was merged.