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:

node/tools/doc/html.js

Lines 394 to 412 in 8429295

	async function altDocs(filename, docCreated) {
	const [, docCreatedMajor, docCreatedMinor] = docCreated.map(Number);
	const host = 'https://nodejs.org';
	const versions = await getVersions.versions();
	const getHref = (versionNum) =>
	`${host}/docs/latest-v${versionNum}/api/${filename}.html`;
	const wrapInListItem = (version) =>
	`<li><a href="${getHref(version.num)}">${version.num}` +
	`${version.lts ? ' <b>LTS</b>' : ''}</a></li>`;
	function isDocInVersion(version) {
	const [versionMajor, versionMinor] = version.num.split('.').map(Number);
	if (docCreatedMajor > versionMajor) return false;
	if (docCreatedMajor < versionMajor) return true;
	if (Number.isNaN(versionMinor)) return true;
	return docCreatedMinor <= versionMinor;
	}

[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).