Docs: Previous version docs pages have broken link to latest version

[pimlottc]

On the docs pages for older revisions of the specs, there's a notice alert that tells the user there's a newer version of the spec, which is great. Unfortunately, the link to the latest version is broken on most (all?) pages.

Note You are not reading the most recent version of this documentation. v3.0 is the latest version available.

Examples:

• http://docs.openreferral.org/en/v2.0/hsds/
  • Links to: http://docs.openreferral.org/en/v3.0/hsds/
  • Should link to: https://docs.openreferral.org/en/v3.0/
• https://docs.openreferral.org/en/v2.0/hsds/about/
  • Links to: https://docs.openreferral.org/en/v3.0/hsds/about/
  • Should link to: https://docs.openreferral.org/en/v3.0/hsds/about.html
• https://docs.openreferral.org/en/v2.0/design_principles/
  • Links to: https://docs.openreferral.org/en/v3.0/design_principles/
  • Should link to: https://docs.openreferral.org/en/v3.0/design_principles.html

This applies equally to v2.0.1 pages as well.

[pimlottc]

This is particularly irksome since many of these older pages are the top hits on Google: #449

[mrshll1001]

Thanks for flagging this!

The underlying issue is that the pages no longer have a direct correspondence to pages on the latest version of the docs. Unfortunately, this issue also persists when using the RTD's built-in sidebar :-/

I think a fair step is editing the notices on each the 2.0 and 2.0.1 branches to do the following:

• change the word 3.0 to latest (since eventually we'll likely have more version updates in the future)
• changing the target of the hyperlink so that it'll always resolve to the landing page for the latest version e.g. http://docs.openreferral.org/en/latest/

This will always guarantee to dump them out at the latest version of the docs, but the tradeoff is that they'll then need to locate and navigate to specific content from there.

[mrshll1001]

I have investigated this and it appears that it may be something we have to live with, at least in the medium term.

This banner is injected by RTD because we've enabled it in the settings for the project (docs). It's a binary option, so either we get it or we don't.

Thankfully, the 3.0 is also auto-generated, and will update with each new "latest" version number.

The little control we do have over the banner is that we can control where on the page it is injected, but not the comment or the target of the link. It's basically working as designed, because the "404" link page actually states the following message:

Documentation changes over time and pages are moved around. You can try to navigate to the index page of the project and use its navigation, or search for a similar page.

The only way we could approach this would be to use some client-side scripting to grab the anchor element for the link and change the href property. Alternatively, we could migrate the sphinx project away from readthedocs and play with the plugin which generates the message. This would involve setting up some complex parallel infrastructure just for this issue, though.

I think either of these would be overkill for something like this, considering it is intended behaviour for Read the docs.

I'm going to leave this issue open for now just in case someone has particularly strong feelings to the contrary, but I really think there's nothing actionable we can do given the limitations of the platform. The underlying issue, as stated, is that we've evolved the structure of the documentation pages. Thankfully, this has been done as part of a MAJOR version change from 2.0.1 to 3.0, so backwards compatibility should not be expected.

[dan-odsc]

@greggish Are you happy for this to be closed?

[greggish]

So we did take these two actions?

• change the word 3.0 to latest (since eventually we'll likely more version updates in the future)
• changing the target of the hyperlink so that it'll always resolve to the landing page for the latest version e.g. http://docs.openreferral.org/en/latest/

If so, seems fine to me given the alternatives...

[mrshll1001]

@greggish as per previous comment:

• the wording is generated by RTD itself, and therefore it'll always update to the latest version. If we jump to 3.1, we can expect the old docs links to say 3.1 as well.
• the target of the hyperlink will resolve to the version of the page in the latest branch. If there is no equivalent page (due to docs reorganisation), then RTD actually explicitly states this to the user and directs them to the landing page. Sadly, we cannot change this behaviour on RTD :-( If we wanted to address this, it would involve setting up our own build servers and infrastructure and modifiying the behaviour of our copy of the plugin that RTD use for this.

Ultimately, it's functioning as intended, regardless of how jarring we find it :-/

I propose we should close this issue, and open a new one to frame the discussion of whether this issue is worth migrating our documentation builds to some privately hosted sphinx docs which we have control over.

[mrshll1001]

Closed in favour of wider discussion in #490