WIP: Use Intersphinx extension for classref links, solving 404 in localized versions

[akien-mga]

We currently don't include the classes/ folder in localized versions, for two reasons:

• Enabling them for parsing by sphinx i18n features would be quite a hassle, because it would include all the markup and method declarations as translatable strings, which would be confusing to translators.
• Until this content is properly translated, it might mess up SEO even more by linking people to localized instances for their English version of the classref.

To address the first point, I plan to work later on on a proper i18n workflow to extract the strings from the original XML, and allow translating them as a separate Weblate projects. The translations could then also be made available offline in the editor. Once we have that, we can work on also integrating those translations in the https://github.com/godotengine/godot-docs-l10n repo for the ReadTheDocs build.

Until then, I plan to use sphinx.ext.intersphinx to make all classref references in localized instances links to the English docs. There are some drawbacks of course:

• Those references lead to another website, which might be confusing to users
• The classref won't appear in the localized docs' search engine

But I think it might be better than the current 404 anyway.

This is very much WIP as there are various things I still need to figure out.

Aims to address #3162.

[akien-mga]

I don't like the fact that even on local builds and on the English docs, the classref links will go through this intersphinx mapping instead of keeping a local reference.

But so far I couldn't find documentation on how to do things in a better way. It should be either:

• An intersphinx feature to provide a "self" reference when not is_i18n (couldn't find any reference to such feature).
• A sphinx feature to let us define a dummy api cross-reference role similar to the one intersphinx would define, but which would do nothing on not is_i18n. Couldn't find any reference to that either.
• Possibly doable, but needs research: defining a custom :api: role that would convert the reference based on whether we are is_i18n or not. That would be the best solution as we could then keep links as

  :api:`class_node`

  instead of

  :ref:`api:class_node`

  , but the docs for creating custom rst roles is not immediately obvious to me: https://docutils.sourceforge.io/docs/howto/rst-roles.html

[akien-mga]

I tried to implement the last option, but I'm stuck. I can't find a way to register a role that simply wraps :api: to :ref:, I'd have to resolve the class_node label myself to find out the URI of the page...

If anyone wants to dig into that stuff: https://github.com/akien-mga/godot-docs/tree/test-sphinx-role-api

[akien-mga]

I don't really like the current WIP, as it means that even on the English docs, we'll reference https://docs.godotengine.org/en/latest/classes/ directly (even in a local build), so we can't use the local copy of the classref. That feels pretty hacky.

The other options I mentioned above in a comment don't seem possible, or if they are, they likely require digging into sphinx or docutils code to figure out how to re-implement :ref: in a custom role... Meh.

So I think the least bad option might be to include a copy of the classref in all localized repos, and just disable its parsing by gettext, at least until we're ready to open it for translation.

[mhilbrunner]

I think we went with the copy now, so we can now close this? If you still planned something with this reopen of course :)

[akien-mga]

Yeah intersphinx turned out hard to manage. I'm going the fully l10n way now, but there's some work left to make it possible.