[ci] Fix version matching between RTD pages and R-package pages

[StrikerRUS]

I believe this element selectors are quite unreliable and subject to frequent changes.
OK, it's shadow DOM, so we simply cannot access it.

Unfortunately, this fix will be active only with next release and is not backported to previous versions.

[StrikerRUS]

@jameslamb Could you please enable RTD builds for this branch for testing?

[jameslamb]

Sure! Done. The first build just started: https://readthedocs.org/projects/lightgbm/builds/25905740/

[StrikerRUS]

Thank you!

[StrikerRUS]

One more issue is that stable leads to 4.0.0 (and not 4.5.0) version of R-package docs.
https://lightgbm.readthedocs.io/en/stable/R/reference/

[StrikerRUS]

I believe it's ready for reviews.

[jameslamb]

Thanks for this! I don't know much about Javascript but I clicked around https://lightgbm.readthedocs.io/en/ci-rtd-r-version/R/reference/ and https://lightgbm.readthedocs.io/en/ci-rtd-r-version/ and the changes look good to me.

On vague idea to consider... could any of this version-replacement be done at build time instead of runtime, with sed or similar?

I did that recently in another project's sphinx Makefile and found it worked well:

https://github.com/rapidsai/legate-boost/blob/fea797e58718edb27e9ab5a054edeaa476ac047d/docs/Makefile#L17-L29

If that's possible, then it'd be nice for a few reasons:

• less Javascript to maintain (which we don't have a lot of maintainer experience with)
• docs site would load faster and more reliably

I'm marking this "Approve" because I support merging this and don't want these question to block it.

[StrikerRUS]

@jameslamb Hey, great idea about build time changes!

I'll try to implement it in conf.py since that file already contains a lot of installation code and it won't be neccesary to duplicate the logic in make.bat.

This PR isn't critical, so I think we shouldn't merge the current fix.

[StrikerRUS]

One more issue is that stable leads to 4.0.0 (and not 4.5.0) version of R-package docs.

Looks like RTD really treats stable as 4.0.0. Build hashes are the same

@jameslamb
Could you please help with this issue?

Linking
#5342
#5930

[jameslamb]

hmmmm I don't understand that. Because at https://readthedocs.org/projects/lightgbm/versions/, it looks to me like readthedocs recognizes that stable and v4.5.0 refer to the same commit.

But I do see that the "Edit on GitHub" button at https://lightgbm.readthedocs.io/en/stable/ links to https://github.com/Microsoft/LightGBM/blob/d73c6b530b39a18a3cacaafc4e42550be853c036/docs/index.rst (which is v4.0.0). That suggests that this issue isn't limited to just the R package.

I just manually triggered a build of stable like this:

build link: https://readthedocs.org/projects/lightgbm/builds/25960601/

Let's see if that fixes it. If it does, then maybe we have to manually trigger a build for stable for every release (I'd assumed that just updating the stable tag here at GitHub would be enough).

[StrikerRUS]

This PR is ready for new review.

[StrikerRUS]

@jameslamb

I just manually triggered a build of stable like this:

Seems that helped!

Maybe the following code is related?

LightGBM/docs/conf.py

Lines 142 to 148 in 668bf5d

	# The version info for the project you're documenting, acts as replacement for
	# |version| and |release|, also used in various other places throughout the
	# built documents.
	# The short X.Y version.
	version = (CURR_PATH.parent / "VERSION.txt").read_text(encoding="utf-8").strip().replace("rc", "-rc")
	# The full version, including alpha/beta/rc tags.
	release = version

Ref:
readthedocs/readthedocs.org#10935 (comment)
readthedocs/readthedocs.org#11183
and other issues in RTD repo with stable in the title: https://github.com/search?q=repo%3Areadthedocs%2Freadthedocs.org+stable&type=issues

[jameslamb]

This all looks great to me @StrikerRUS , thank you for your hard work! I think the links you shared are very relevant, especially that code link showing the docs build reading VERSION.txt.

It seems to me that this PR plus manually rebuilding stable on every release should be enough.

Please merge this whenever you want.

[jameslamb]

I also just added an about triggering a new stable readthedocs build to the release checklist at #6538, so we'll remember the next time we make a release.

[StrikerRUS]

@jameslamb Thanks! Yeah, I believe that manual triggering is only the option for us for now, unfortunately.

[StrikerRUS]

@jameslamb And I'd like to ask you to remove ci-rtd-r-version branch on RTD since it's not needed anymore. 😃

[jameslamb]

done!

[StrikerRUS]

Hmmm...
It's still visible in version selector widget. Hope it's temporarily before next build. Previously, removed branches disappeared immediately.

[jameslamb]

Maybe you need to refresh your browser cache?

I don't see it when I navigate to https://lightgbm.readthedocs.io/en/latest/index.html

Or in the project settings at https://readthedocs.org/projects/lightgbm/versions/

[StrikerRUS]

Thanks for the suggestion!
Nevermind, it's gone without any actions from my side.