Invalid/404 links to the online documentation in the editor help class reference

[1shevelov]

Your Godot version:
3.2.2.stable.official

Issue description:

1. invalid link https://docs.godotengine.org/en/latest/tutorials/gui/bbcode_in_richtextlabel.html on built-in docs page "Class: RichTextLabel"
   Should link to "stable" instead of "latest", because "latest" is missing.

2. invalid link https://docs.godotengine.org/en/latest/getting_started/scripting/gdscript/gdscript_basics.html#dictionary on built-in docs page "Class: Dictionary"
   The same issue.

[1shevelov]

BTW, I'm sure there are more of these errors. Is there an issue already for this that I just have not found?

[Calinou]

Lots of pages were moved around in the master branch recently, and links in the class reference haven't been updated for that yet.

We generally choose to link the latest branch in the class reference because it's the most up-to-date version. It takes a while for things to be cherry-picked into the stable branch.

[1shevelov]

The built-in docs can't have the same version as the tool(engine) that has them? Or everything will be allright after docs revision in 3.2.4 or 4.0?
@Calinou, sorry, not sure I understood you well. So skip the explanation, if the topic is complicated. I just wanted to be sure that devs are aware of this issue.

[Calinou]

The built-in docs can't have the same version as the tool(engine) that has them? Or everything will be allright after docs revision in 3.2.4 or 4.0?

If we linked to the stable branch, we'd link to outdated documentation for people using the Godot master branch. If we linked to the latest branch (which is what we currently do), we'd link at documentation that's too-up-to-date for people using a stable version of Godot like 3.2.3.

I'm not sure if there's a good solution to this problem. cc @NathanLovato

One of my ideas was to replace the /latest/ part with a variable in the URLs and replace it automatically with a suitable version identifier (or branch name) in the Godot editor help. We'd also have to modify makerst.py to support this.

[NathanLovato]

@1shevelov what you're seeing now happens because we started working on the docs for Godot 4.0 and that breaks some changes. I didn't know the class reference linked to the latest version of the docs, which is the work-in-progress version for the next major release. From Godot 3.0 to 3.2.X it wasn't an issue but now the engine is getting so many changes and we're reorganizing the docs, it's causing some.

@Calinou the only robust solution I see to this issue is properly maintaining both versions of the docs in parallel and yes, not linking to latest/ but to a specific version of the docs. And using latest/ only for nightly builds or so. But we'd need docs maintenance on both branches in parallel because changes happen even in minor/bugfix Godot releases. Sometimes even breaking ones.

[omicron321]

1. yes, each doc pages needs to link to their proper branch version, because from branch to another, links just get broken, as page get moved or renamed
2. small updates/typos for given stable branch (2.... 3....) should be done... in their given branch, and immediately cherry picked to master if appropriate, and to ulterior stable branches if appropriate too. Working the other way from latest is not efficient as updates are more numerous and additionnaly needs to be checked as relevant or not to be cherry picked (while almost always true in the other way I suppose)

I am currently using stable doc, but can't report/send fixes to things as i see them: gh links are broken, and inexistant latest.

[NathanLovato]

1. Isn't possible right now, it's a limitation of the backend, read the docs: redirects affect all branches. Making the changes on the stable docs would just have broken everything.
2. Either way is fine, for typos etc. it doesn't change the workload so much. But in either case, you need a maintainer ~full-time to do that. It's not that people aren't aware of the issues, it's there's nobody available to do the tedious cherry-picking work. If someone wants to put in the hours, they're welcome to do so, as usual.

[Calinou]

For future reference, this should be fixed by #5414 once it's done.

[mhilbrunner]

This is now fixed, both by #5414 / followups like #5541 and in-engine links being branch specific.