Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Adding a version picker for Synapse docs #16533

Merged
merged 8 commits into from
Dec 11, 2023

Conversation

Dmytro27Ind
Copy link
Contributor

@Dmytro27Ind Dmytro27Ind commented Oct 22, 2023

🚀 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:

  1. Merge the pull request.
  2. 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.

ver-picker-1 ver-picker-2 ver-picker-3

Pull Request Checklist

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

Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
@Dmytro27Ind Dmytro27Ind requested a review from a team as a code owner October 22, 2023 18:21
Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
@erikjohnston
Copy link
Member

@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)

@erikjohnston erikjohnston requested review from a team and removed request for a team November 29, 2023 11:38
Copy link
Member

@erikjohnston erikjohnston left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Needs updating)

Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
@Dmytro27Ind
Copy link
Contributor Author

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

Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
changelog.d/16533.doc Outdated Show resolved Hide resolved
@Dmytro27Ind
Copy link
Contributor Author

@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

Copy link
Member

@anoadragon453 anoadragon453 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you very much for tackling this - this is something I've personally wanted to see added since we introduced the documentation website :)

A few small comments below, but on the whole lgtm.

docs/website_files/version-picker.js Outdated Show resolved Hide resolved
docs/website_files/version-picker.js Outdated Show resolved Hide resolved
docs/website_files/version-picker.js Outdated Show resolved Hide resolved
.github/workflows/docs-add-version-picker.yaml Outdated Show resolved Hide resolved
Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
Signed-off-by: Dmytro Kagirov <dmytro27kagirov@gmail.com>
Copy link
Member

@anoadragon453 anoadragon453 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the changes. This now looks good to me!

Merging, and will run the new GitHub action.

@anoadragon453 anoadragon453 merged commit 483d22a into matrix-org:develop Dec 11, 2023
32 checks passed
@Dmytro27Ind
Copy link
Contributor Author

@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
Copy link
Member

anoadragon453 commented Dec 11, 2023

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 483d22a 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!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Github pages docs: include Synapse version on the page somewhere other than the URL
3 participants