Update Sphinx version and migrate to sphinx-multiversion CLEWS-33782 #292
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 7 commits
December 1, 2020 19:07
- upgrades Sphinx from 1.5.6 (from 2017-05) to 3.1.2 (2020-07) - switch to sphinx-multiversion from sphinxcontrib-versioning Relevant changes in Sphinx are mostly a bunch of bugfixes and improved HTML output: https://www.sphinx-doc.org/en/master/changes.html Some of the HTML output got a little fancier, but not that noticable. (Sphinx 3.1.2 is chosen because Sphinx 3.2.0 adds local link checking, which doesn't quite work right with our docs. Also see #291)
instead of hiding the branch version selectors with CSS, we just don't include them via the versions template. improvement from the previous sphinxcontrib-versioning setup: now, the development branch docs are included in the selector alongside the version tags.
replicating another sphinxcontrib-versioning feature in sphinx-multiversion. functionality is identical.
The old sphinxcontrib-versioning extension has a handy 'push' command to build and push new documentation to a git branch. The sphinx-multiversion extension we're transitioning to doesn't have this, so we replicate it with a shell script.
i'm not sure why the ssh-agent/ssh-add /tmp/ssh/00_sub bit was added in the first place, but it shouldn't be necessary, as this identity should be added automatically: http://docs.shippable.com/ci/ssh-keys/ tested manually and shippable still seems to be able to push to gh-pages without it.
For some reason, when running on shippable, the '\t' escape pattern for matching tabs with grep doesn't work. So, we just drop the tab from the pattern since it's not that important.
muzigao
approved these changes
Dec 2, 2020
muzigao
added a commit
that referenced
this pull request
Nov 12, 2021
Update Sphinx version and migrate to sphinx-multiversion CLEWS-33782
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This upgrades Sphinx from 1.5.6 (from 2017-05) to 3.1.2 (2020-07), and migrates from sphinxcontrib-versioning (SCV) to sphinx-multiversion (SMV). These extensions both enable building multiple versions of our docs. SCV hasn't been updated since 2016, and doesn't work with more recent versions of Sphinx (see sphinx-contrib/sphinxcontrib-versioning#78 and sphinx-contrib/sphinxcontrib-versioning#69). More recent versions of Sphinx are needed so that we can use nbsphinx in #282.
The main complexity here is from the new script sphinx_push_ghpages.sh, which replicates functionality that SCV have which was missing from SMV. I've tested this quite a bit and I'm pretty confident that it's working correctly, including when called from Shippable.