Node: Docs only shows version subset in navigation

[codebytere]

• Browser version: Chrome Version 80.0.3987.106
• Operating system: macOS 10.14

When viewing a given API reference on the website, there's an option to view another version:

It allows for a user to pick another version to swap to and see relevant docs, but it's constrained by what existed at the time the _currently chosen doc_ was written. This means that e.g when a user picks v11.x, they won't be able to go back to v13.x:

without first going back to v12.x.

I'd say this is an antipattern, and that we should unilaterally be storing the versions available in the most recently defined major line. If this seems like a good path forward, i'm happy to implement this myself!

[Trott]

I'd say this is an antipattern, and that we should unilaterally be storing the versions available in the most recently defined major line. If this seems like a good path forward, i'm happy to implement this myself!

I agree.

[nschonni]

@Trott do you want to transfer this one to the Node repo? I think this needs to be fixed there since it's for the API docs generated there

[richardlau]

+1 from me.

@codebytere If you haven't already discovered it, the existing drop down is generated at build time here:
https://github.com/nodejs/node/blob/8429295c5b2bf3eb52a5b57eaceaffc3158a0c4a/tools/doc/html.js#L394-L412

[Trott]

@Trott do you want to transfer this one to the Node repo? I

I'll let @codebytere move it if she wants to. Wherever it makes the most sense for her. (Argument for this repository might be that people noticing the problem are likely to look here for an issue about it. Argument for the core repository is that's where the work might have to happen. Although I can also imagine changing things there so that the menu is generated here instead. I don't know.)

[codebytere]

@richardlau do you know where website logging occurs? Preliminary poking around indicated that it's falling back to local file read 100% of the time to show versions, meaning that the https call to read the changelog from master isn't working 🤔

[richardlau]

@richardlau do you know where website logging occurs? Preliminary poking around indicated that it's falling back to local file read 100% of the time to show versions, meaning that the https call to read the changelog from master isn't working 🤔

I'm not sure what logging you're asking for.

The code that does the https call is in https://github.com/nodejs/node/blob/master/tools/doc/versions.js.

[codebytere]

right, yes, that's what i'm referencing. e.g if i'm correct and

console.warn(Unable to retrieve ${url}. Falling back to ${file}.);

is being hit, where would that be logged to?

[richardlau]

right, yes, that's what i'm referencing. e.g if i'm correct and

console.warn(Unable to retrieve ${url}. Falling back to ${file}.);

is being hit, where would that be logged to?

stderr usually.

e.g. if I edit the URL so it's not found:

diff --git a/tools/doc/versions.js b/tools/doc/versions.js
index 782ce90..d57baf7 100644
--- a/tools/doc/versions.js
+++ b/tools/doc/versions.js
@@ -42,7 +42,7 @@ module.exports = {
     // The CHANGELOG.md on release branches may not reference newer semver
     // majors of Node.js so fetch and parse the version from the master branch.
     const url =
-      'https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG.md';
+      'https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG0.md';
     let changelog;
     const file = path.join(srcRoot, 'CHANGELOG.md');
     if (kNoInternet) {

then

-bash-4.2$ NODE=out/Release/node make doc-only
npm WARN prepare removing existing node_modules/ before installation
added 105 packages in 1.403s
mkdir -p out/doc/api
cp -r doc/api out/doc
make[1]: Entering directory `/home/users/riclau/sandbox/github/nodejs'
if [ -x /home/users/riclau/sandbox/github/nodejs/out/Release/node ] && [ -e /home/users/riclau/sandbox/github/nodejs/out/Release/node ]; then /home/users/riclau/sandbox/github/nodejs/out/Release/node  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js; elif [ -x `which node` ] && [ -e `which node` ] && [ `which node` ]; then `which node`  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js; else echo "No available node, cannot run \"node  tools/doc/apilinks.js out/doc/apilinks.json lib/_http_client.js lib/net.js lib/_tls_wrap.js lib/http.js lib/dns.js lib/tls.js lib/fs.js lib/path.js lib/domain.js lib/timers.js lib/_http_outgoing.js lib/events.js lib/child_process.js lib/_http_agent.js lib/tty.js lib/querystring.js lib/async_hooks.js lib/url.js lib/http2.js lib/https.js lib/zlib.js lib/perf_hooks.js lib/_stream_readable.js lib/buffer.js lib/punycode.js lib/trace_events.js lib/cluster.js lib/_stream_duplex.js lib/process.js lib/_http_common.js lib/stream.js lib/sys.js lib/_http_incoming.js lib/_stream_passthrough.js lib/_stream_writable.js lib/repl.js lib/string_decoder.js lib/constants.js lib/v8.js lib/assert.js lib/_stream_wrap.js lib/util.js lib/_stream_transform.js lib/wasi.js lib/module.js lib/vm.js lib/console.js lib/crypto.js lib/inspector.js lib/_http_server.js lib/os.js lib/dgram.js lib/readline.js lib/worker_threads.js lib/_tls_common.js\""; exit 1; fi;
if [ -x /home/users/riclau/sandbox/github/nodejs/out/Release/node ] && [ -e /home/users/riclau/sandbox/github/nodejs/out/Release/node ]; then /home/users/riclau/sandbox/github/nodejs/out/Release/node  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api; elif [ -x `which node` ] && [ -e `which node` ] && [ `which node` ]; then `which node`  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api; else echo "No available node, cannot run \"node  tools/doc/generate.js --node-version=v14.0.0 --apilinks=out/doc/apilinks.json doc/api/path.md --output-directory=out/doc/api\""; exit 1; fi;
Unable to retrieve https://raw.githubusercontent.com/nodejs/node/master/CHANGELOG0.md. Falling back to /home/users/riclau/sandbox/github/nodejs/CHANGELOG.md.
...

[codebytere]

yes haha sorry i don't think i'm asking this question well - On the website itself, when that codepath is executed, where should i be going to confirm that the error is being logged to stderr?

E.g in Electron we use papertrail for our website logging - that's where i'd go to track down an issue of this nature. Where is that analogous logging for Node.js' website? does it exist?

[richardlau]

yes haha sorry i don't think i'm asking this question well - On the website itself, when that codepath is executed, where should i be going to confirm that the error is being logged to stderr?

It isn't? The drop down is a static list generated when the API docs are built. So the code I've been linking to only ever runs on the release machine.

E.g in Electron we use papertrail for our website logging - that's where i'd go to track down an issue of this nature. Where is that analogous logging for Node.js' website? does it exist?

¯\_(ツ)_/¯ I don't know. Maybe someone from @nodejs/website or @nodejs/build-infra does.

[XhmikosR]

AFAICT this stuff is only logged during build time; the toggler is static, no JS is involved client-side apart from the highlighting library (SHJS).

[alexandrtovmach]

I'm not sure that we have some system for logs in any of nodejs websites. It's overhead for simple websites, that not contains any specific functionality.

[rvagg]

@codebytere what you're looking for is in ci-release, in your release job, the docs are generated by the "sources" builder (specifically centos7-release-sources), so navigate to that one and look at the full console log and you'll find tools/doc/generate.js output in there. So for your 13.10.0 build you can see this in: https://ci-release.nodejs.org/job/iojs+release/5706/nodes=centos7-release-sources/consoleFull
If you want to test out any code changes here then feel free to run some test jobs through ci-release from your fork since you have access to do so, just _make sure_ you select "test" from the dropdown and use the proper 10-char commit hash and proper date and it should show up nicely in https://nodejs.org/download/test/ (edit: there's up to a 5 minute delay from completion of a builder to publishing the resources, so if centos7-release-sources finishes but you don't see your docs or even your new directory, be patient).

Some thoughts about this:

• This needs to work offline and away from nodejs.org, docs should be usable as purely static resources. Which explains why it is the way that it is. But doesn't preclude there being better options for upgrading the UX when it can.
• Instead of doing this at build time, have a mode that's "if I'm online and can fetch resources from nodejs.org, fetch nodejs.org/download/release/index.json, form a release line menu from that and show it". People reading the docs from nodejs.org should be able to make fetch calls to that JSON file and it should be pretty simple to parse it down into a release line selector list.

[codebytere]

Awesome, that's exactly what i was after @rvagg! I'll start with that approach.