Adding a version picker for Synapse docs

Dmytro27Ind commented 1 year ago

🚀 Adding a version picker for Synapse docs

In this pull request I've added a version picker for the Synapse docs. The problem was that we need to add this version picker for all previous versions of the docs (not just develop). So in addition to adding a version picker, I also wrote a github action to add a version picker for all previous versions of the docs. This action "Add Version Picker (RUN ONCE)" needs to be run manually for develop branch and only once, because then the version picker will be in all versions of the docs and then we don't need to run this action anymore,

📋 Related Issues

This pull request is related to this issue: #15692, #11647

📝 Instructions

To properly add the version picker, follow these steps:

Merge the pull request.
Manually run the GitHub action "Add Version Picker (RUN ONCE)" (docs-add-version-picker.yaml) for develop branch to update the documentation for previous versions.

📷 Screenshots

As you can see this version picker, can handle all themes.

Pull Request Checklist

[x] Pull request is based on the develop branch
[x] Pull request includes a changelog file.
[x] Pull request includes a sign off
[x] Code style is correct.

Signed-off-by: Dmytro Kagirov dmytro27kagirov@gmail.com

erikjohnston commented 11 months ago

@Dmytro27Ind Sorry that this hasn't been reviewed yet. We've recently fixed our ability to preview documentation for PRs, so if you could merge in develop then hopefully it'll be easier for us to review (as we'll be able to play around with the real thing)

Dmytro27Ind commented 11 months ago

@erikjohnston Hello. I have fixed the conflicts and also added v1.97. Now you can review it

Dmytro27Ind commented 11 months ago

@erikjohnston It seems that PR Documentation Preview (https://pr16533--synapse-docs-previews.netlify.app/) only builds the current version of the documentation. You can see the verison picker, but if you change the version, you'll see the not found page:

If you want to be able to play around with it, you can create a fork and build the documentation in your fork. For example, I built it in my fork and you can see the result here: https://dmytro27ind.github.io/synapse/v1.95/

PS v1.96, v1.97 and the latest versions don't work in my github pages documentation preview because I built it over a month ago on v1.95

Dmytro27Ind commented 10 months ago

@anoadragon453 Hello. I checked it on https://matrix-org.github.io/synapse/develop/ and the version picker works well, but for the latest tag you have several choices:

you can rebuild the latest documentation tag (gh-pages/latest)
or wait for a new version of Synapse (with the new version the version picker will be added to the latest tag automatically),
or you can add the version picker to the latest tag manually.

P.S. to see the version picker, you need to switch from the latest tag to any tag in the url line. In other words, version picker is now available everywhere except the latest tag

anoadragon453 commented 10 months ago

Hi @Dmytro27Ind, thanks for the run down!

We'll (hopefully) be doing another release of Synapse tomorrow, so I think that'd be the easiest path forwards. Otherwise we'd need to cherry-pick https://github.com/matrix-org/synapse/commit/483d22afc39d96b5e25292843806d0c0487e6446 to master, but to avoid any potential merge conflicts during the release process, it's probably safer to just wait til tomorrow.

Still, it looks excellent on the live version'd pages that are up now. Thank you for your work!

matrix-org / synapse