Inline code hightlighting

[Qubus0]

while working on #11217 i was curious if it was possible to add inline code highlighting like we have it for the mod loader docs, and it turns out that it is possible by adding this to the files

.. role:: gd(code)
   :language: gdscript

The following is the list of supported operators and their precedence. All binary operators are `left-associative <https://en.wikipedia.org/wiki/Operator_associativity>`_,
including the :gd:`**` operator. This means that :gd:`2 ** 2 ** 3` is equal to :gd:`(2 ** 2) ** 3`. Use parentheses to explicitly specify precedence you need, for
example :gd:`2 ** (2 ** 3)`. The ternary :gd:`if/else` operator is right-associative.

which does result in all the proper code highlights.

Before	After

note that :language: gd results in the old lexer being used, i think, so not everything is properly highlighted, but :language: gdscript works just fine.

now the question - do we want this? it's neat, but also quite some effort to pull through everywhere, especially when tables break. also new contributions should probably use this too, which adds a bit more contribution friction

regex replace with

``(.*?)``
:gd:`$1`

does work alright, but of course not everything is gdscript

[Calinou]

This looks pretty nice! I've been wanting to have inline code highlighting for a while. It's certainly something I'd like to see on more websites in general.

The hard part will be to comb through the existing pages and ensure we're only using :gd: for inline code that is actually GDScript. Maybe we'll need a :cs: role for C# code in the long run too.

[Qubus0]

yep we probably would need that. i think we could start with this on the main gdscript pages where we could get the biggest benefit with the smallest chance for error.? for /classes the code that converts from bbcode [code] to backticks would need to be adjusted of course.

[Calinou]

for /classes the code that converts from bbcode [code] to backticks would need to be adjusted of course.

This code is in the main Godot repository: https://github.com/godotengine/godot/blob/master/doc/tools/make_rst.py

However, we don't have explicit tagging of inline GDScript code right now (everything uses [code]), so we'd need to do that first by combing through the class reference in the main Godot repository (and adding editor support for the tags).

[Cykyrios]

I'd like to see inline syntax highlighting as well, especially in the editor (but it's nice to have in the online documentation as well), but having the same kind of options as codeblocks, with [code lang=text] to disable highlighting, seems like an absolutely necessary option, as we cannot assume that everything typed within [code] tags is GDScript code.

From the above screenshot comparison, we can see the if/else being colored as if + division + else, which is probably not the intended output here (although it does look nice this way). Other instances where this may create issues is when typing a path, like [code]user://path/to/some/file.txt[/code], which is not wrapped in quotes, and will have colored slashes and dots.

Having the option to enable/disable it from the tag itself should also make it more export-friendly (for the Godot Mod Loader, my own GDScript XML converter project, and maybe others).

For reference, grep -o -P '\[code\]' | wc -l returns 125339 results, so I wish the best of luck to those who plan to comb through those 🥲. I'm sure many of those are just [code]true[/code], or numbers, or maybe variable names, but we're also likely to find something that should not be syntax-highlighted here and there.

[Qubus0]

the ternary if was just from the way the code was wrapped, this is how it looks when fixed

what do you mean with this?

Having the option to enable/disable it from the tag itself

whew that's a lot of [code]... i think it's safe to say we'd first cover all the manually written docs and try to get the class reference afterwards, when the editor is ready to handle [code] with language specifier

[Cykyrios]

By "option" I just meant having [code lang=text] like we have [codeblock lang=text], because if we don't things may get messy in some situations.

Separating if and else in the ternary does look better 👍.