Links from c Modules to Lua Modules in documentation don't work
HHHartmann opened this issue · comments
See the link on https://nodemcu.readthedocs.io/en/dev/modules/node/#example_7
Expected behavior
point to https://nodemcu.readthedocs.io/en/dev/lua-modules/telnet/
Actual behavior
points to https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua-modules/telnet/ which does not exist
Test code
The link is as follows: ../lua-modules/telnet.md
NOTE:
links like ../../app/modules/node.c work as desired and point to https://github.com/nodemcu/nodemcu-firmware/tree/dev/app/modules/node.c
NodeMCU startup banner
N/A
Hardware
irrelevant
Prior discussion starts here:
#3489 (comment)
@marcelstoer commented 2 days ago
Oh, just realized we have the same issue on the BME280 math page.Caused by this https://github.com/nodemcu/nodemcu-firmware/blob/release/docs/js/extra.js#L46
@HHHartmann commented 2 days ago
Staring at the code not knowing much about js it might be that adding a "/" to the relativePath might do the job.
I assume that the dots are evaluated as wildcats matching any character. Thus effectively matching the intended start of "../../dev" but also "../lua-modules"@marcelstoer commented 2 days ago
With the docs a lot of stuff isn't as it may seem - and much of it stems from the requirement of having links work both while browsing GitHub and inside the docs.
- In the original
node.md
with haveSee [the telnet lua module](../lua-modules/telnet.md) for...
-> relative link 1 level up- His works when browsing GitHub
- When this is built into the HTML structure by RTD/MkDocs this becomes
<p>See <a href="../../lua-modules/telnet/">the telnet lua module</a> for a working
-> relative link 2 levels up
- This is basically fine (MkDocs ensures all relative links are consistent) as we want to go from
https://nodemcu.readthedocs.io/en/dev/modules/node/index.html#nodeinput
to
https://nodemcu.readthedocs.io/en/dev/lua-modules/telnet/index.html- It clashes, however, with all links that already have
../../
in the original.md
. This is used in links to.c
source files for example:[node.c](../../app/modules/node.c)
. MkDocs realizes those links point beyond the docs structure and keeps them as-is (rather than adding another level).- Our JavaScript code can't tell the two apart and applies the "fix" to both.
Side note: in JavaScript the pattern in
String.prototype.replace()
can be a string or a RegExp; we use it with a string.
Actually I thought about the
$("div.section a[href^='" + relativePath + "']")
snippet.
It selects everything that has a "/" in the third position. But reading your explanations it seems to be different.
What about if we only adapt links to ../../dev.
Maybe check if there are other links to the sources or find a negative pattern that matches everything but "modules" and "lua-modules"
But then there are md files in other places too which might get linked.
Maybe apply the tweak only to urls that start with "../.." and do not end with "/", or better have nothing but an ancor (#) after the "/"
I'll take a look later this week I hope.
What about if we only adapt links to ../../dev.
Well, the tweak cannot be branch-dependent.
I was thinking about checking whether the link points to any of the dirs in the /docs folder. Those are the ones that the tweak must not be applied to as anything inside this dir is (correctly) managed by MkDocs.
Well done. Works as expected
Thanks for testing Gregor