Repository: litestar-org/litestar

Issue:
Documentation: "older version" warning present on latest
Every page under https://starlite-api.github.io/starlite/latest/ has the "You are viewing the documentation for an older version of Starlite. Click here to get to the latest version" warning, which links back to the welcome page. 

The message is not present in https://starlite-api.github.io/starlite/1.50/, https://starlite-api.github.io/starlite/1.49/, or https://starlite-api.github.io/starlite/1.47/.
Documentation: "older version" warning present on latest
Every page under https://starlite-api.github.io/starlite/latest/ has the "You are viewing the documentation for an older version of Starlite. Click here to get to the latest version" warning, which links back to the welcome page. 

The message is not present in https://starlite-api.github.io/starlite/1.50/, https://starlite-api.github.io/starlite/1.49/, or https://starlite-api.github.io/starlite/1.47/.


Discussion:
Yep, seeing this too. Thanks for the report!
`versions.json` still shows 1.49 with the "latest" alias:

https://github.com/starlite-api/starlite/blob/cf7772c782fab24d090f9b4b5d9a201d163b6a62/versions.json#L1

However, this doesn't explain why the the banner doesn't show on 1.48, for example.
> However, this doesn't explain why the the banner doesn't show on 1.48, for example.

Seems to be a big in the workaround I added to make the versioning compatible with the one we had for mkdocs. I’m gonna put a PR to fix this later.
`getSelectedVersion()` returns "latest":

![image](https://user-images.githubusercontent.com/20659309/215424544-c41d6638-a941-40f4-a2ac-bbb81cefbf5b.png)

the latest version is defined here, and is "1.50" in this case, and the way this is selected means it will always be the 0th entry in that array of version, irrespective if it is actually aliased as "latest" or not.

https://github.com/starlite-api/starlite/blob/c7ed593ec491401b55881dca9af231b8f99f843a/docs/_static/js/version_select.js#L91

So, `selectedVersion` will never match `latestVersion` here when `selectedVersion` is "latest":

https://github.com/starlite-api/starlite/blob/c7ed593ec491401b55881dca9af231b8f99f843a/docs/_static/js/version_select.js#L34

Perhaps, `getSelectedVersion()` should resolve the actual version of the "latest" alias?

OK, will leave it with you @provinzkraut 
> However, this doesn't explain why the the banner doesn't show on 1.48, for example.

Quick correction - I do get a banner for 1.48, but not 1.47 or 1.49
> Perhaps, getSelectedVersion() should resolve the actual version of the "latest" alias?

This would be a bit tricky since we currently don't actually use the aliasing anymore. I didn't want to add the complexity of re-aliasing and such to the docs publishing logic, and we don't actually need it, since we have a pre-defined versioning scheme, so no need for the flexibility really. 

The solution here would be to just hardcode `"latest"` in the check for the latest version, so that it always returns true for `"latest"`.
So this is why 1.49 is "latest" in versions.json? It doesn't actually mean anything in practice?
This is the versioning logic that `mike` used. I simply haven't touched that. The idea was to just keep it as-is, so everything would continue working on the older versions of the documentation. Seems like I'm going to have to remove that alias from the versioning file and slap it on to the actually *latest* version so our old docs display the correct warnings + offer redirects.

For our docs, it doesn't do anything, that's correct. However, since it looks like we're going to have to use the alias to make the older docs work, we might as well use it for ours as well.
Yep, seeing this too. Thanks for the report!
`versions.json` still shows 1.49 with the "latest" alias:

https://github.com/starlite-api/starlite/blob/cf7772c782fab24d090f9b4b5d9a201d163b6a62/versions.json#L1

However, this doesn't explain why the the banner doesn't show on 1.48, for example.
> However, this doesn't explain why the the banner doesn't show on 1.48, for example.

Seems to be a big in the workaround I added to make the versioning compatible with the one we had for mkdocs. I’m gonna put a PR to fix this later.
`getSelectedVersion()` returns "latest":

![image](https://user-images.githubusercontent.com/20659309/215424544-c41d6638-a941-40f4-a2ac-bbb81cefbf5b.png)

the latest version is defined here, and is "1.50" in this case, and the way this is selected means it will always be the 0th entry in that array of version, irrespective if it is actually aliased as "latest" or not.

https://github.com/starlite-api/starlite/blob/c7ed593ec491401b55881dca9af231b8f99f843a/docs/_static/js/version_select.js#L91

So, `selectedVersion` will never match `latestVersion` here when `selectedVersion` is "latest":

https://github.com/starlite-api/starlite/blob/c7ed593ec491401b55881dca9af231b8f99f843a/docs/_static/js/version_select.js#L34

Perhaps, `getSelectedVersion()` should resolve the actual version of the "latest" alias?

OK, will leave it with you @provinzkraut 
> However, this doesn't explain why the the banner doesn't show on 1.48, for example.

Quick correction - I do get a banner for 1.48, but not 1.47 or 1.49
> Perhaps, getSelectedVersion() should resolve the actual version of the "latest" alias?

This would be a bit tricky since we currently don't actually use the aliasing anymore. I didn't want to add the complexity of re-aliasing and such to the docs publishing logic, and we don't actually need it, since we have a pre-defined versioning scheme, so no need for the flexibility really. 

The solution here would be to just hardcode `"latest"` in the check for the latest version, so that it always returns true for `"latest"`.
So this is why 1.49 is "latest" in versions.json? It doesn't actually mean anything in practice?
This is the versioning logic that `mike` used. I simply haven't touched that. The idea was to just keep it as-is, so everything would continue working on the older versions of the documentation. Seems like I'm going to have to remove that alias from the versioning file and slap it on to the actually *latest* version so our old docs display the correct warnings + offer redirects.

For our docs, it doesn't do anything, that's correct. However, since it looks like we're going to have to use the alias to make the older docs work, we might as well use it for ours as well.

Resolving patch:
diff --git a/tools/publish_docs.py b/tools/publish_docs.py
--- a/tools/publish_docs.py
+++ b/tools/publish_docs.py
@@ -12,7 +12,7 @@
 parser.add_argument("--latest", action="store_true")
 
 
-def update_versions_file(version: str) -> None:
+def add_to_versions_file(version: str, latest: bool) -> None:
     versions_file = Path("versions.json")
     versions = []
     if versions_file.exists():
@@ -24,6 +24,11 @@ def update_versions_file(version: str) -> None:
     else:
         versions.insert(0, new_version_spec)
 
+    if latest:
+        for version in versions:
+            version["aliases"] = []
+        versions[0]["aliases"] = ["latest"]
+
     versions_file.write_text(json.dumps(versions))
 
 
@@ -32,7 +37,7 @@ def make_version(version: str, push: bool, latest: bool) -> None:
 
     subprocess.run(["git", "checkout", "gh-pages"], check=True)
 
-    update_versions_file(version)
+    add_to_versions_file(version, latest)
 
     docs_src_path = Path("docs/_build/html")
     docs_dest_path = Path(version)


Test patch: