✨ ENH: Support version and locale switcher #360
Conversation
cheekyshibe
changed the title
|
Excellent thanks for picking this one up! Is there a way that we could demo this in the documentation? The theme isn’t translated to any other languages, but perhaps we can try this with the version switcher to see how things look? |
We have not yet provided the English version on our official website (so as you can see, the paths of Here is the way we tested the version switcher (you can use it the same way on demo site locally):
|
|
@MegChai, thanks for picking this up! At first glance it looks good on your site. For the language selector on your site, it looks like it may get cluttered if there is more than ~2 possibilities there, did you consider adding another dropdown selector for that? I'll try and review this and test it out on a different local site build within the next couple of days. |
You are right. The support for multi-language should be like what we have done for multi-version. Maybe it can also be generated from
|
|
yep @MegChai using a dropdown for this as well sounds like a good idea, since many projects will have several languages. |
There was a problem hiding this comment.
@MegChai, I tried to test it out on a local project and ran into some issues with finding the proper version number from the URL (I think my local build is missing that path), so my dropdown selector was never getting populated. I also left a few other thoughts and comments here too. Overall, I think this is definitely heading in the right direction!
| @@ -21,3 +21,8 @@ search_bar_position = sidebar | |||
| navigation_with_keys = True | |||
| show_toc_level = 1 | |||
| navbar_align = content | |||
| use_version_switch = True | |||
There was a problem hiding this comment.
I think this (and enable_locale) should probably default to False start as an opt-in in case other people are already rolling their own version switcher?
| </li> | ||
| <li class="nav-item"> | ||
| <span id="locale-switcher"> | ||
| <!-- placeholder for locale switcher --> |
There was a problem hiding this comment.
Replace with dropdown like above. I also liked your suggestion of putting the country flags in there, I'm not sure how hard it is to go from locale to UTF-8 flag code, but it would be a nice touch to add.
| } | ||
| if (pathname.slice(-pageName.length) !== pageName) { | ||
| // Sphinx generated pages should have exactly same suffix | ||
| throw 'page suffix do not match requirements'; |
There was a problem hiding this comment.
Do we want to throw here (and below)? Or do, we want to just fail gracefully somehow. If any of the parsing failed, maybe remove the version switcher element altogether? Or fill it with a go-to-home button instead. I'm not sure what the best path is.
| // This is base URL without any version or locate. | ||
| let globalBaseURL = parts.join('/') | ||
|
|
||
| return {pageName, baseURL, currentVersion, currentLocale, globalBaseURL}; |
There was a problem hiding this comment.
When I was testing this locally, I was getting an empty string for currentVersion, which caused everything downstream to fail for me. I think this may be because the project is serving up the html build directory /index.html and not /en/v1.3/index.html. I'm not sure if this has to do with Sphinx options when I set up the project or not, but I think this will probably need to be robust against local builds for testing too where the URL may not be fully populated with locale and version.
|
@MegChai thanks for the PR! A few suggestions:
|
|
This branch has been not maintained for a long time, @ThuWangzw will work on another branch. He will open a new pull request as soon as possible. |
Refs: MegEngine#1 / #276 / #23
@greglucas FYI.
Create a simple version switcher to change versions and locales.
Features
theme_use_version_switch=Trueand settheme_version_switch_json_url = "/versions.json", then you will get an nicely dropdown menu that render everything from/versions.jsontheme_version_switch_enable_locale