[ci][docs] replace file extensions in docs during Sphinx build

[StrikerRUS]

@jameslamb I remember you proposed this change some time ago. But I was against because was not bought of idea to rewrite all docs source files during the build process. Now I know that we can do it via internal Sphinx process which doesn't require rewriting files on a disk. Also, this approach safer than rewriting files because we are sure our regex is applied only to links in docs (self.document.traverse(reference)) not to the whole document.

Live demo: https://lightgbm.readthedocs.io/en/sphinx/

[jameslamb]

ooooo yeah this is great! I just tried clicking through https://lightgbm.readthedocs.io/en/sphinx/ and it seems like internal links are all doing what we'd expect (including in the R package).

[StrikerRUS]

@jameslamb Thanks!

all doing what we'd expect (including in the R package)

Another +1 for this way of replacing extensions because R-package docs will be unaffected as they are outside of the Sphinx build tree. 😉 (We simply pick up their folder after Sphinx is finished.)

LightGBM/docs/conf.py

Lines 305 to 307 in eb9bbfb

	app.connect("build-finished",
	lambda app, exception: copy_tree(os.path.join(CURR_PATH, os.path.pardir, "lightgbm_r", "docs"),
	os.path.join(app.outdir, "R"), verbose=0))

[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.