RTD: Add compatibility fixes for upstream changes at Read The Docs #535
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
When invoking Sphinx standalone, we need to preconfigure a few variables to make the RTD compatibility package work.
amotl
force-pushed
the
msbt/rtd-addons-fix
branch
from
cc9f865 to
f02303c
Compare
amotl
changed the title
sphinx-build-compatibility
... to permit publishing `crate-docs-theme` to PyPI.
... after switching to new GitHub Issues.
... to respect `linkcheck_anchors_ignore_for_url` configuration setting, needed for handling new GitHub Issues.
amotl
reviewed
Oct 8, 2024
Comment on lines
56
to
66
| # We are using APIv2 to pull active versions, downloads and subprojects | ||
| # because APIv3 requires a token. | ||
| try: | ||
| response_versions = requests.get( | ||
| f"{scheme}://{production_domain}/api/v2/version/?project__slug={project_slug}&active=true", | ||
| timeout=2, | ||
| ).json() | ||
| versions = [ | ||
| (version["slug"], f"/{version['project']['language']}/{version['slug']}/") | ||
| for version in response_versions["results"] | ||
| ] |
There was a problem hiding this comment.
On the preview for crate-reference, intending to restore the version chooser, it looks like this now:
Now, the question is if it will be all good on the live site, or if it will also start displaying all the PR builds, for whatever reason, which we certainly want to avoid.
There was a problem hiding this comment.
Well, yeah. It would probably also happen on the live site. Why does this always happen to me?
$ http 'https://readthedocs.org/api/v2/version/?project__slug=crate&active=true' | jq '.results[].slug'
"master"
"latest"
"5.8"
"5.7"
"4.8"
"3.3"
"16732"
"16731"
"16729"
"16728"
There was a problem hiding this comment.
Maybe APIv2 has a bug, but I couldn't figure out the right parameters.
APIv3 however works well, like before, so we will just update the URL pattern accordingly.
$ http 'https://readthedocs.org/api/v3/projects/crate/versions/?active=true' | jq '.results[].slug'
"master"
"latest"
"5.8"
"5.7"
"4.8"
"3.3"
There was a problem hiding this comment.
c0c0929 adds a fix by adjusting the RTD compat layer. Now, this spot looks like before.
The `sphinx-build-compatibility` code needed to be improved where inquiring project metadata. The v2 API returns or started returning inactive builds (PR numbers) in inquiries to active project versions. The v3 API works much better. The project language will be inquired separately.
amotl
reviewed
Oct 8, 2024
Comment on lines
+56
to
+84
| # We are using APIv2 to pull active versions, downloads and subprojects | ||
| # because APIv3 requires a token. | ||
| try: | ||
| response_project = requests.get( | ||
| f"{scheme}://{production_domain}/api/v3/projects/{project_slug}/", | ||
| timeout=2, | ||
| ).json() | ||
| language = response_project["language"]["code"] | ||
| except Exception: | ||
| logger.warning( | ||
| "An error ocurred when hitting API to fetch project language. Defaulting to 'en'.", | ||
| exc_info=True, | ||
| ) | ||
| language = "en" | ||
|
|
||
| try: | ||
| response_versions = requests.get( | ||
| f"{scheme}://{production_domain}/api/v3/projects/{project_slug}/versions/?active=true", | ||
| timeout=2, | ||
| ).json() | ||
| versions = [ | ||
| (version["slug"], f"/{language}/{version['slug']}/") | ||
| for version in response_versions["results"] | ||
| ] | ||
| except Exception: | ||
| logger.warning( | ||
| "An error ocurred when hitting API to fetch active versions. Defaulting to an empty list.", | ||
| exc_info=True, | ||
| ) |
There was a problem hiding this comment.
This fragment has been adjusted to yield better results for this theme, see #535 (review).
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.
About
https://about.readthedocs.com/blog/2024/07/addons-by-default/
References