Distinguish stable from latest documentation

[astrojuanlu]

Description

At the moment, stable and latest versions of the docs are identical visually speaking, which might confuse users. cc @stichbury

Context

Today a user was confused because they thought that latest meant "latest stable version", when in fact means "latest development version" https://www.linen.dev/s/kedro/t/13226075/dataset-factory-hi-everyone-i-m-experimenting-with-dataset-f#2842ff79-1d6c-4859-a5f9-f93fcfa50ca8

(also cc @humitos can latest be renamed on RTD? or is it hardcoded?)

Possible Implementation

Add version warning for latest docs, like the one we have for older versions:

Possible Alternatives

❓

[stichbury]

How would this work so it was only ever on latest? Would we be able to control this through RTD or have to add it manually and remove it again for releases, then add it back for the next?

[humitos]

(also cc @humitos can latest be renamed on RTD? or is it hardcoded?)

You can take different approaches here, depending on your goal:

• make latest to point to the branch/tag you want from the project's setting by defining the "Default branch"
• disable latest version completely if you want
• set "Default version" to something different than latest (this is the "Default version" setting)
• override latest by creating a branch/tag with that name

Can you expand a little more on the goal?

[noklam]

@humitos I guess it is because "latest" refers to our "main" branch while stable refer to the latest release.

Some user try to find docs in latest and mistaken it refers to the latest version.

[datajoely]

Can we rename latest , nightly? is that clearer that it's WIP?

[astrojuanlu]

Can you expand a little more on the goal?

It looks like "latest" means "latest stable version" to some users, so we'd like to know if it's possible to rename it to something like nightly, unreleased, or similar.

(I think "nightly" is very obvious for developers but not so much for users)

[astrojuanlu]

In any case, this issue has two parts: renaming latest (if possible) and more importantly adding some visual element that tells the user that they're reading documentation of features that aren't yet available in a released version of Kedro (should be easy)

[astrojuanlu]

Renaming latest is not an option.

About the visual cues, we can either wait until RTD solves the search-as-you-type glitches of the add-ons and make use of readthedocs/addons#125, or use https://sphinx-version-warning.readthedocs.io/ instead.

[humitos]

About the visual cues, we can either wait until RTD solves the search-as-you-type glitches of the add-ons and make use of readthedocs/addons#125,

This is fixed and it should be released in the next few days.

or use sphinx-version-warning.readthedocs.io instead.

I don't think I will keep maintaining this extension anymore in the future, since it will be superseded by the addons notification.

[astrojuanlu]

Thanks to the new RTD add-ons, this is already being done.

[astrojuanlu]

Btw, now that readthedocs/readthedocs.org#10674 was addressed, I went ahead and enabled the main version and renamed it to nightly.

This means that now we should have 2 versions: stable and nightly. Hence the latest version, which was very confusing, should remain hidden. cc @ankatiyar @DimedS

About stable, I still think it should be a redirection:

And on the topic of the flyout, here's my thinking:

I think I have become numb to the whole stable/latest from RTD, but I think @stichbury is right this is not at all obvious.

Now, look at what happens when I change the default version to be 0.19.3 instead of the current stable:

1. User types https://docs.kedro.org
2. User gets redirected to https://docs.kedro.org/en/0.19.3/
3. The flyout shows the number:

By having the number in the URL and also in the flyout by default, I think it's more obvious how the user should go and switch to their version of choice.

Originally posted by @astrojuanlu in #3741

[astrojuanlu]

Amazing ❤ https://ai.pydantic.dev/