Set edit_uri option on Mkdocs projects for better integration

[marcelstoer]

Details

• Read the Docs project URL: https://nodemcu.readthedocs.io and https://docs.readthedocs.io
• Build URL (if applicable):
• Read the Docs username (if applicable):

Expected Result

The "Edit on GitHub" top right should take you to the page on GitHub on the selected branch and open it for editing (requires GH authentication).

Actual Result

For MkDocs projects

Regardless of which branch you selected it always links to the master branch - which might not even have that page. Examples:

• https://nodemcu.readthedocs.io/en/dev-esp32/en/modules/bthci/ links to https://github.com/nodemcu/nodemcu-firmware/edit/master/docs/en/modules/bthci.md -> 404 as the file doesn't exist there
• https://nodemcu.readthedocs.io/en/latest/en/getting-started/ links to https://github.com/nodemcu/nodemcu-firmware/edit/master/docs/en/getting-started.md -> wrong as "latest" is configured to be the dev branch rather than master

For RTD itself

As far as I can tell there's only a problem with the "stable" alias. However, that might be because there are only stable and latest.

• https://docs.readthedocs.io/en/stable/ links to https://github.com/rtfd/readthedocs.org/blob/16be3aed72f87b5d1228bdd442c271b2c5912124/home/docs/checkouts/readthedocs.org/user_builds/docs/checkouts/stable/docs/conf.py/index.rst -> 404

Side note

Similar issues have existed for the "branch selector" for quite some time (fly-out or dropdown bottom right) but there are other issues for that AFAIR.

[stsewd]

As far as I can tell there's only a problem with the "stable" alias. However, that might be because there are only stable and latest.

That one was because of an old build I believe, we should just retrigger a new build on the stable docs.

[stsewd]

A new build was triggered on the stable version of rtd, the url is correct now

[stsewd]

I'll investigate about the mkdocs issue, not sure where the link is injected

[stsewd]

We don't do anything with that, putting master is the default behavior from mkdocs https://www.mkdocs.org/user-guide/configuration/#edit_uri (read the note). But I think this would be a nice to have for the mkdocs integration, similar to #4820

[marcelstoer]

Thanks for the super quick analysis! Now as I read that (again) I remember it to be vaguely familiar. Conclusion is that I could potentially fix that myself (by editing mkdocs.yml in the branches) - at least temporarily until e.g. the dev branch is merged to master.

So yes, support from RTD in an integration task would be greatly appreciated.

Otherwise, I'd have to resort to a JavaScript hack fixing the link URL on page load in the browser.

[stsewd]

So, I have brought this to the team, I'd say we don't have a final decision yet, our main concern is that the mkdocs.yml could change that options, and we don't have a way to identify the mkdocs version that the users are running, so things can break. I'm changing the title to reflect the request and adding the design decision label.

[stsewd]

edit_uri has been from the 0.16.0 version of mkdocs https://www.mkdocs.org/about/release-notes/#other-changes-and-additions-to-version-0160

[humitos]

We are moving away of "magically" do things on behalf of the user for particular doctools. We are now going to expose some extra environment variables that doctool/theme authors could use to integrate properly with us. See #9423

[humitos]

I'm closing this issue since we don't plan to add more "magic manipulation" on our build process --in fact, we are removing as much as we can from it. The user should the environment variables passed to the build process https://docs.readthedocs.io/en/stable/reference/environment-variables.html#envvar-READTHEDOCS_GIT_CLONE_URL to define edit_uri as they prefer.