Expose another environment variable for PR builds

[pmeier]

RTD already exposes the READTHEDOCS environment variable to provide the option for changed behavior if it is building the docs.

It would be nice to have an additional environment variable, e.g. READTHEDOCS_PR, that will only be set if the current build was initiated from a PR.

[humitos]

I'm 👍🏼 on this. However, the name of the variable may be something like READTHEDOCS_EXTERNAL_VERSION="True" to match what we are using in other places --in particular, because GitLab uses MR instead of PR 😞

[stsewd]

This is implemented in #8237, but using READTHEDOCS_VERSION_TYPE.

[pmeier]

It seems #8237 is stuck. Could we maybe have this feature first, which could be superseded by #8237 later?

[stsewd]

I think we can port the changes that add the new env vars (https://github.com/readthedocs/readthedocs.org/pull/8237/files#diff-99dfd740f4f146e66e1c3709bebdc3db357a8c6defbf3e592434be4308f5d697), and leave out the other change about improving the name shown for external builds.

[pmeier]

@stsewd Anything I can help with to get this merged?

[nightlark]

Having a way (probably environment variable) to get if the build is for a PR or not would be useful (or type of RTD build), along with branch information:

• the name of the branch being built (or the head ref/branch for PRs)
• the base branch if the build is a PR

[TheTripleV]

As a solution in the meantime, https://github.com/wpilibsuite/sphinxext-delta/ detects and only runs on PR builds on RTD (if your source code is on GitHub).

The PR detection is at https://github.com/wpilibsuite/sphinxext-delta/blob/1ce65493eb26db0e8d9575b7b3ddc1737963077a/sphinxext/delta.py#L39-L43.

def on_pr(html_context: Dict[str, str]) -> bool:
    return (
        html_context["github_version"].startswith(html_context["commit"])
        or os.getenv("GITHUB_EVENT_NAME") == "pull_request"
    )

We use it in combination with RTD detection at https://github.com/wpilibsuite/sphinxext-delta/blob/1ce65493eb26db0e8d9575b7b3ddc1737963077a/sphinxext/delta.py#L97.

[astrojuanlu]

Hi @TheTripleV, thanks for sharing your solution! I'm curious, how did you realize that the GITHUB_EVENT_NAME environment variable was being set in the html_context? To my knowledge, we are not doing that on purpose, but maybe I'm missing something here.

[TheTripleV]

To be honest, that might be something that Github Actions sets. on_pr() detects PR builds on both RTD and Github Actions while on_rtd() detects RTD. That's why we use the combination of the two for that extension.

[pmeier]

With #8237 merged, one now can do os.getenv("READTHEDOCS_VERSION_TYPE") == "external" to get a boolean flag for PR builds.