Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Fix --branch magic to not collide variable with sphinx tags #2073

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

woju
Copy link
Member

@woju woju commented Nov 29, 2024

Description of the changes

See commit message.
Fixes: #2066

How to test this PR?

READTHEDOCS=1 READTHEDOCS_VERSION=stable make -C Documentation html
firefox Documentation/_build/html/run-sample-application.html

and look at the git clone invocation in the first listing. make html should be successful, but no --branch in the listing. Now:

make -C Documentation clean
git tag v123456-do-not-push
READTHEDOCS=1 READTHEDOCS_VERSION=stable make -C Documentation html
firefox Documentation/_build/html/run-sample-application.html

should succeed and have --branch v123456-do-not-push in the listing.

Remember to

git tag -d v123456-do-not-push

before you push.

(Before this commit READTHEDOCS=... make will fail as in https://readthedocs.org/projects/gramine/builds/26350000/)


This change is Reviewable

Copy link
Member

@mkow mkow left a comment

Choose a reason for hiding this comment

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

Reviewed 1 of 1 files at r1, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion, not enough approvals from maintainers (2 more required), not enough approvals from different teams (1 more required, approved so far: ITL) (waiting on @woju)


-- commits line 13 at r1:
Why wasn't this problem detected by CI's Docs pipeline? Do I understand correctly, that it's because we don't test with rtd_current_version == 'stable'? Maybe we should?

A mistake was made in commit c9dca72
("[Docs] quickstart: Add specific checkout to stable versions") that the
variable name (`tags`) was chosen to collide with Sphinx' special
configuration variable:
https://www.sphinx-doc.org/en/master/usage/configuration.html#project-tags
This went unnoticed, because at the time we were not using project tags.
Later, in commit 6ebc605 ("[Docs]
Update sphinx to 5.3"), we started using this feature. The mistake was
still unnoticed, because the stable checkout was under condition that is
true only rarely.

Fixes: c9dca72 ("[Docs] quickstart: Add specific checkout to stable versions")
Fixes: 6ebc605 ("[Docs] Update sphinx to 5.3")
Signed-off-by: Wojtek Porczyk <[email protected]>
@woju woju force-pushed the woju/docs-fix-git-tags branch from c3a23a1 to c9e2d3f Compare November 29, 2024 15:53
Copy link
Member Author

@woju woju left a comment

Choose a reason for hiding this comment

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

Reviewable status: 1 of 2 files reviewed, 1 unresolved discussion, not enough approvals from maintainers (2 more required), not enough approvals from different teams (1 more required, approved so far: ITL) (waiting on @mkow)


-- commits line 13 at r1:

Previously, mkow (Michał Kowalczyk) wrote…

Why wasn't this problem detected by CI's Docs pipeline? Do I understand correctly, that it's because we don't test with rtd_current_version == 'stable'? Maybe we should?

That's complicated, we'll have to create a testing tag for git tag --points-at to work. I'm not saying no, but we'd have to be careful with this tag not to push it anywhere (should someone change out CI to CD). I've pushed one possible version, see docs.jenkinsfile, but I'm not proud of that piece of engineering.

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

Successfully merging this pull request may close these issues.

stable version of gramine readthedocs is not updated with changes done as part of v1.8 release
2 participants