Documentation Issue on Read the Docs

[critfest]

Environment info

Operating System:

CPU/GPU model:

C++/Python/R version:

LightGBM version or commit hash:

Error message

Reproducible examples

Steps to reproduce

1. Go to https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html
2. Click any link with a .rst extension (there were at least four I found)
3. You get an error page stating:
   " SORRY /
   \ /
   \ This page does /
   ] not exist yet. [ ,'|
   " like this: https://lightgbm.readthedocs.io/en/latest/README.rst

[StrikerRUS]

@critfest
Sorry, I can't reproduce the issue. Please point to the concrete link.

[hayesall]

@critfest I've only been able to reproduce this behavior by clicking links in view-source mode.

<a class="reference external" href="./FAQ.rst#i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm">Question 4</a>

Can you include the browser you are using (and version if available)? I haven't been able to reproduce this in Firefox 68.0.1 or Chrome 75.

[jameslamb]

We should be replacing all of those per #2272 (comment)

[StrikerRUS]

We should be replacing all of those per #2272 (comment)

Yeah, RTD requires JS enabled. @critfest Please ensure that JS is enabled in your browser or any third-party software is not blocking it.

[jameslamb]

@StrikerRUS OH! When you showed me that before, I didn't realize it ran on page load in the browser.

I think we should write a hook in our conf.py that does that replacement when generating the HTML content. That way, we'd never have a browser-specific problem (it would just be static HTML) but it would still preserve the desired behavior of having .rst links so links inside the repo work.

I would be happy to write this if you think it's a good idea @StrikerRUS (and would love your input @hayesall )!

[StrikerRUS]

@jameslamb I considered this option when was initially reworking docs. I abandoned the idea to replace links at Python side due to additional dependencies (e.g. bs4). The current links replacement is done by very simple jQuery function (jQuery is already imbedded into RTD). I'm not sure that it's possible to do the same at Python side elegantly without additional dependencies. Nowadays, practically all sites cannot work without JS properly, and the only requirement we have is enabled JS.

That way, we'd never have a browser-specific problem (it would just be static HTML)

We have other things at JS side which are impossible to replace with Python equivalent. Moreover, RTD itself cannot work without JS.

[jameslamb]

Ok makes sense! Thanks for educating me on some of the history of our docs this week. The "I don't want to take on a BeautifulSoup dependency" I think could be avoided (I was thinking of literally matching a regular expression for .rst links) but the argument that we have other JS stuff which is harder to replace is convincing.

[hayesall]

@StrikerRUS Hey, sorry for not following up on this earlier, but I think it would be worth adding this to #2302 as "noscript-compatible documentation."

People sometimes block JavaScript for security or privacy reasons. Most of this documentation is generated as static content, so retaining an option for users who disable JavaScript should be considered.

[StrikerRUS]

@hayesall

Hey, sorry for not following up on this earlier, but I think it would be worth adding this to #2302 as "noscript-compatible documentation."

Unfortunately, it's unresolvable issue, which we'll never fix. I don't think that we need such issue in our list.

Moreover, RTD site itself cannot work without JS enabled.