PR: Add support for docs versions

[dalthviz]

Pull Request Checklist

• Read and followed this repo's Contributing Guidelines
• Based your PR on the latest version of the correct branch (master or 3.x)
• Checked your writing carefully for correct English spelling, grammar, etc
• Described your changes and the motivation for them below
• Noted what issue(s) this pull request resolves, creating one if needed

Description of Changes

Currently only builds local branches that follow the regex in the config (branches with <number>.<anything> names and master).

NOTE: The theme being installed needs to be changed for the proper repo/branch after spyder-ide/spyder-docs-sphinx-theme#33 is merged

A preview:

Depends on spyder-ide/spyder-docs-sphinx-theme#33

Issue(s) Resolved

Fixes #179

[ccordoba12]

@dalthviz, please don't forget to update the way our docs are installed in Netlify to check how your work looks there.

[CAM-Gerlach]

@dalthviz I'm not sure what specifically @ccordoba12 is referring to, but Netlify needs to be set to clone all branches like you did for Travis or only the current branch will show up in the dropdown on Netlify, as you can see in the preview. Not sure how best to do this with Netlify, but I'm sure you do.

[ccordoba12]

I'm not sure what specifically @ccordoba12 is referring to

To use make multidocs instead of make docs there.

but Netlify needs to be set to clone all branches like you did for Travis or only the current branch will show up in the dropdown on Netlify

I don't know if that's possible because Netlify is in charge of cloning the repo (users don't control part).

[dalthviz]

To use make multidocs instead of make docs there.

For that we merged #186 and rebased this (since other PRs like #181 need to use make docs instead of make multidocs to generate a preview at least until we merge this PR).

Netlify needs to be set to clone all branches

@CAM-Gerlach I was thinking about that too although, as @ccordoba12 says, I'm unsure if it's possible. I will need to check

[dalthviz]

Seems like Netlify builds a detached HEAD of the PRs without remotes:

Also thinking a little bit more, maybe having all the versions on the preview isn't actually needed right @CAM-Gerlach @ccordoba12 ? At the end when you are doing a modification you target that to only one version (depending on the base branch the PR sets) and I think Netlify puts your changes and builds that specific branch/version

[ccordoba12]

maybe having all the versions on the preview isn't actually needed right?

Sure, we can go without that for now.

[ccordoba12]

I have some comments about the style though:

• I think we should style "Versions" in the same way as the rest of the text on the sidebar.
• "Versions" should be aligned with the title of the page or be a little below it.
• There's a margin on the left that prevents "Versions" and the dropdown to be aligned with "Search".
• We should style the dropdown in the same way as "Search".

---

My proposal (this also changes the border of "Search" a bit):

#versions-header {
    color: rgba(0,0,0,.65);
    font-size: 0.8rem;
    text-transform: uppercase;
    margin-top: 1.1rem;
}

#select-versions {
    margin-bottom: 7px;
    border: 1px solid rgba(0, 0, 0, 0.15)
    font-size: 90%;
    color: rgba(0,0,0,.65);
    padding: 2px;
}

#select-versions, #select-versions option {
    width: 98%;
}

.form-control {
    box-shadow: none;
    background: transparent;
    border: 1px solid rgba(0, 0, 0, 0.15);
    height: 54px;
    font-size: 18px;
    font-weight: 300;
}

[CAM-Gerlach]

@ccordoba12 As I've mentioned previously (somewhere... :) ) I've been working on that for a while and will push my changes shortly. It ended up being way more complicated to both do that and also build the current feature/PR branch, because I was having to set the release in conf.py dynamically (in order to also rename the output directories accordingly) and couldn't figure out any way to propagate the right state or env variables all the way through to the sub-build to get it to work reliably cross-platform but I think I've got it solved now.

[CAM-Gerlach]

Just a few smaller style things, and one code issue. Otherwise, this should be good to go on my end. Thanks!

[CAM-Gerlach]

⚠️ ⚠️ ⚠️ REMINDER: MERGE THEME PR AND CHANGE BEFORE MERGING THIS ONE!!! ⚠️ ⚠️ ⚠️

[CAM-Gerlach]

@dalthviz , @juanis2112 noticed that in Safari, the selector functions, but displays the wrong branch (always the current one) once the page is loaded. In Chrome, we can both confirm that it starts off on the default selection on page load, but within a couple hundred ms is set to the correct one, and in FF it is always correct from when the page first starts to render, but in Safari it says set to the current branch permanently.

[juanis2112]

Apart from the small blink that CAM commented, everything works fine for me. Thanks @dalthviz and @CAM-Gerlach!

[CAM-Gerlach]

@juanis2112 I fixed the "blink" issue with the version selector, and made a few related behind the scenes improvements

@dalthviz A few last changes:

• Make the setupVersionSelector() function fire when the DOM is ready, instead of only when all external resources are loaded, to ensure it triggers earlier to reduce the window in which it is non-functional for users on slow connections (and originally to reduce or eliminate the blink, but I fixed it entirely with the next change
• Statically set the option that is selected via a check in the Jinja template, and eliminate the now-unnecessary JS that sets it, so that it is set correctly from the very beginning and avoid the need for the extra complexity, fragility and delay it introduces
• Only run setupVersionSelector() if there is a version selector on the page (e.g. make docs; I didn't observe any console errors or bad behavior but better safe than sorry)
• Minor style tweaks and kill blank spaces

[CAM-Gerlach]

LGTM @dalthviz , I think this one is ready and everyone has approved. Thanks so much for your work! Can you and @juanis2112 recheck my last changes to fix the "<blink>" issue, and if everything looks good to both of you, go ahead and merge after merging spyder-ide/spyder-docs-sphinx-theme#33 and unsetting the custom theme branch.

[CAM-Gerlach]

@juanis2112 rechecked and it looks good, so @dalthviz you're free to go ahead with the above, thanks.