[docs] [R-package] use CRAN-style builds when building pkgdown site

[jameslamb]

This PR proposes using CRAN-style builds of the R package on readthedocs (RTD).

Advantages of this approach over CMake builds:

• (maybe) faster RTD builds, since cmake does not need to be installed
• easier updates of the conda R dependencies for RTD builds
• reduced risk of failures when the RTD images change (since the CRAN package is optimized for portability)
• another step towards publishing vignettes on the {pkgdown} site (contributes to [R-package] Rewrite R demos, replace with vignettes #1944)
  • I say this because I'm going to propose on [R-package] [docs] add intro vignette #3946 that we only build vignettes for CRAN-style builds of the R package

[jameslamb]

@StrikerRUS can you please re-enable my docs/jlamb branch at readthedocs? I see it isn't being built: https://readthedocs.org/projects/lightgbm/builds/

[StrikerRUS]

@jameslamb

Sure, done! Just a note: we need to keep RTD versions clean (test something and then remove dev branch) because we've started to provide versions for previous releases (#4236). Excess branches might confuse users there.

[jameslamb]

we need to keep RTD versions clean (test something and then remove dev branch)

Thanks! Yep, I understand. As long as I do not have permissions on RTD to do this myself, I'll have to ask you to add and remove a dev branch when I want to test docs.

[jameslamb]

I see that the most recent build failed with an error like this.

-- Building favicons -----------------------------------------------------------
Building favicons with realfavicongenerator.net...
Error : API request failed.
...
...
...
Error: <callr_status_error: callr subprocess failed: API request failed.>
-->
<callr_remote_error in NULL:
 API request failed.>
 in process 1834 

 Stack trace:

 Process 1819:
 1. pkgdown::build_site(lazy = FALSE, install = FALSE, devel = FALSE,  ...
 2. pkgdown:::build_site_external(pkg = pkg, examples = examples,  ...
 3. callr::r(function(..., crayon_enabled, crayon_colors, pkgdown_internet) { ...
 4. callr:::get_result(output = out, options)
 5. throw(newerr, parent = remerr[[2]])

 x callr subprocess failed: API request failed. 

 Process 1834:
 17. (function (..., crayon_enabled, crayon_colors, pkgdown_internet)  ...
 18. pkgdown::build_site(...)
 19. pkgdown:::build_site_local(pkg = pkg, examples = examples, run_dont_run = r ...
 20. pkgdown:::init_site(pkg)
 21. pkgdown:::build_favicons(pkg)
 22. base:::stop("API request failed.", call. = FALSE)
 23. base:::.handleSimpleError(function (e)  ...
 24. h(simpleError(msg, call))

 x API request failed. 

Execution halted
)

https://readthedocs.org/projects/lightgbm/builds/14472426/

That seems unrelated to the changes in this PR. I'm going to try pushing an empty commit to re-trigger the build.

[jameslamb]

ahhh ok actually, the issue about favicons WAS related to the changes here. I was able to reproduce it locally.

The CRAN-style package doesn't contain the contents of R-package/pkgdown (https://github.com/microsoft/LightGBM/tree/926526c838196a7497a85b6b8cf07657a88b69e6/R-package/pkgdown).

That includes the pkgdown/favicons directory, which was created by pkgdown::build_favicons() (mentioned in #3327 (comment)).

I just pushed 5138946, which I think should fix it.

[jameslamb]

I just pushed 5138946, which I think should fix it.

Ok yep, that worked! The RTD build is passing (https://readthedocs.org/projects/lightgbm/builds/14472810/), and the R documentation looks correct to me (https://lightgbm.readthedocs.io/en/docs-jlamb/R/index.html).

I believe this is ready for review.

[StrikerRUS]

LGTM!
I like the advantages you've listed above 🙂 .

As long as I do not have permissions on RTD to do this myself, I'll have to ask you to add and remove a dev branch when I want to test docs.

I can remove a dev branch by default after merging a PR associated with that branch.

[github-actions]

This pull request has been automatically locked since there has not been any recent activity since it was closed. To start a new related discussion, open a new issue at https://github.com/microsoft/LightGBM/issues including a reference to this.