Backfill some old documentation versions with static assets

[astrojuanlu]

Description

In #3586 we introduced https://github.com/kedro-org/kedro-sphinx-theme across our 3 Sphinx subprojects.

This was done to revert the use of an S3 bucket to hold static assets for reusability #3016.

However, the moment that S3 bucket ceases to exist, several versions of the docs will immediately appear like this:

Fixing this isn't straightforward: https://docs.readthedocs.io/en/stable/versions.html RTD versions are generated from git tags, so modifying old ones requires some work.

We need to understand what would be the impact of this breakage (what versions are affected), come up with a solution, and decide on what versions (if not all) we will apply it.

Context

We don't know how many doc versions are affected, so it is good to figure that out as well.

Possible Implementation

One possible way of doing this is:

1. Pick the old version to fix, for example 0.19.3
2. Create a branch that departs from that tag, for example named 0.19.3.x
3. Make the necessary changes
4. Make a PEP 440 post-release https://peps.python.org/pep-0440/#post-releases, for example named 0.19.3.post1
5. Hide the 0.19.3 version in the docs and show 0.19.3.post1 instead
6. Redirect /en/0.19.3 to /en/0.19.3.post1

Some projects use post-releases to address minor errors in a final release that do not affect the distributed software (for example, correcting an error in the release notes).

I haven't tested this ⚠️ whoever tries this approach should validate it with a personal project first.

Also, the "necessary changes" might be either backporting kedro-sphinx-theme, or even partially reverting #3292.

Possible Alternatives

There might be other ways to do this, ideas welcome.

[rashidakanchwala]

@astrojuanlu - Should we have a similar ticket on Kedro-viz, or should we also assign a Kedro-viz engineer along with Framework to this ticket, so the work can be done across both in this sprint.

[astrojuanlu]

Whatever works best 🙏🏼 I don't have a strong preference

[SajidAlamQB]

We don't know how many doc versions are affected, so it is good to figure that out as well.

I’ve identified the Kedro doc versions that are affected by the s3 bucket. The affected versions are from 0.19.0 to 0.19.4, inclusive.

The s3 implementation was introduced in #3292, which was merged into the develop branch on November 2023.

Reasoning:

Since this was merged into develop, it became part of the next major release, which was 0.19.0. Starting from version 0.19.5, we moved to using the kedro-sphinx-theme instead of relying on s3 bucket. Hence, only versions 0.19.0 to 0.19.4 will break if the s3 bucket is deleted. I have also manually tested and confirmed this.

I will test backporting kedro-sphinx-theme on these versions.

[SajidAlamQB]

I've been testing out the possible implementation outlined above. You can see the new tags in my forked repository here: GitHub Tags. I also created a personal Read the Docs project to test this approach. You can view the results here: RTD Project.

I think there is some limitations with the redirects, particularly with the wildcards we can use. Currently, the redirects are set as /en/0.19.x/* -> /en/0.19.x.post1, which redirects any page from 0.19.x to the 0.19.x.post1 homepage (where x is 0-4 for 0.19.0 to 0.19.4). This may not be the most optimal approach since it doesn't maintain the path of the specific pages.

Would love to hear peoples thoughts on this current implementation and if there are any suggestions for improving the redirects to better handle the specific pages.

[rashidakanchwala]

thanks would this 0.19.x redirect affect future versions of kedro 19 that don't face this issue.

[SajidAlamQB]

thanks would this 0.19.x redirect affect future versions of kedro 19 that don't face this issue.

Sorry, its not 0.19.x by x I meant only versions 0 to 4. so 0.19.0-0.19.4.

[astrojuanlu]

How about this :splat thing @SajidAlamQB ? https://docs.readthedocs.io/en/stable/user-defined-redirects.html#redirecting-an-old-version-to-a-new-one

[SajidAlamQB]

How about this :splat thing @SajidAlamQB ? https://docs.readthedocs.io/en/stable/user-defined-redirects.html#redirecting-an-old-version-to-a-new-one

Perfect this worked, thank you!

[astrojuanlu]

If the approach is proven to work and it took a reasonable effort @SajidAlamQB , given that there are only 5 versions affected, I'd be in favour of executing this, in parallel with the 0.19.6 release.

[SajidAlamQB]

Completed for framework, the new tags can be found here:

https://github.com/kedro-org/kedro/releases/tag/0.19.4.post1 https://github.com/kedro-org/kedro/releases/tag/0.19.3.post1 https://github.com/kedro-org/kedro/releases/tag/0.19.2.post1 https://github.com/kedro-org/kedro/releases/tag/0.19.1.post1 https://github.com/kedro-org/kedro/releases/tag/0.19.0.post1

[SajidAlamQB]

I've kept the new release tags hidden on the version fly-out window as it looks better (see below). The corresponding 0.19.(0-4) versions will go to their respective 0.19.(0-4).post1 link.

[astrojuanlu]

Awesome 🔥

• [x] @SajidAlamQB could you do the same on kedro-datasets? Just gave you maintainer access
• [x] @rashidakanchwala we'll need this on Kedro-Viz as well

[Huongg]

great work @SajidAlamQB 🔥 , let sync up sometimes today so we can follow a similar approach for kedro-viz too 😄

[SajidAlamQB]

All versions of the Kedro-Viz documentation are affected. I’ve backfilled the kedro-sphinx-theme for them, and they all seem to be working well. You can view the tags here: Kedro-Viz Tags.

Some of the .post1 tags’ CI builds are failing, but the docs build fine. I think this should be okay since these tags are just needed for Read the Docs.

[SajidAlamQB]

Completed for kedro-datasets you can view the tags here: https://github.com/kedro-org/kedro-plugins/tags.