Editor Help: Add syntax highlighting for code blocks #89263

dalexeev · 2024-03-07T21:25:04Z

Closes Add highlighting to code blocks in the built-in documentation (and more?) godot-proposals#7617.

## [codeblock]
## func test():
##     pass
## [/codeblock]
## [codeblock lang=text]
## func test():
##     pass
## [/codeblock]
func _run():
    pass

dalexeev · 2024-03-08T10:29:07Z

editor/editor_help.cpp

+	return singleton;
+}
+
+EditorHelpHighlighter::HighlightData EditorHelpHighlighter::_get_highlight_data(Language p_language, const String &p_source, bool p_use_cache) {


This method probably needs a mutex, since a single Script + TextEdit + EditorSyntaxHighlighter are used (within one language). And probably different EditorHelps work in different threads? But I didn't notice any problems during testing however.

editor/editor_help.h

dalexeev · 2024-03-08T10:40:45Z

Please test with C# build, I didn't do that.

By the way, since GDScriptSyntaxHighlighter and CSharpScript + CSharpLanguage (keyword list, etc.) are located in modules, when the module is disabled the corresponding highlighting is disabled too.

Example (set text_editor/help/class_reference_examples editor setting to "GDScript and C#"):

akien-mga · 2024-03-08T11:02:31Z

CC @godotengine/dotnet

I don't think we actually have a C# syntax highlighter currently, so the addition here is theoretical. But it might be a good incentive to add at least a minimal highlighter for docs' sake, or the handful of users who for some reason might be opening C# scripts in the builtin editor instead of a C# IDE :)

akien-mga · 2024-03-08T11:04:21Z

Example (set text_editor/help/class_reference_examples editor setting to "GDScript and C#"):

BTW I forgot we even had this feature, and I assume most users don't know it. We should probably expose this as a button in the EditorHelp that lets you enable GDScript and/or C# snippets (the latter being disabled on non-mono builds). Like it could be one button per language just reusing the language's script icon.

Mickeon · 2024-03-08T11:11:58Z

modules/gdscript/doc_classes/@GDScript.xml

@@ -95,7 +95,7 @@
 				    print(get_stack())
 				[/codeblock]
 				Starting from [code]_ready()[/code], [code]bar()[/code] would print:
-				[codeblock]
+				[codeblock lang=text]


Unless it's derived from somewhere where it's standard, I'd rather be explicit and write the whole parameter name (languange=text) instead.
Also there's other places where this would be needed but for this PR it's completely fine to only use it here as an example.

Unless it's derived from somewhere where it's standard, I'd rather be explicit and write the whole parameter name (languange=text) instead.

Your typo makes a strong case against this suggestion ;)

lang is clear enough and less prone to typos IMO.

Yes, this is a follow-up task for documentation team if this PR gets merged. I corrected only one file to test the RST generator and for example.

BTW an alternative would be to always use [codeblocks][gdscript]... for actual code examples, and thus also make sure we provide C# examples where relevant. And then default to assuming plain text for [codeblock].

Maybe with an optional [codeblock lang=gdscript]/[codeblock lang=csharp] for whenever it really doesn't make sense to provide both languages (e.g. in @GDScript docs).

Up the air now, but this addition has me question if the [codeblocks] + [gdscript]/[csharp] syntax should be replaced by [codeblocks] + [codeblock lang=gdscript/csharp]. Not to break what isn't broke, but just a thought.

We literally wrote the same thing within the same minute

[codeblocks], [gdscript] and [csharp] are more like preprocessor directives that depend on the editor setting. While [codeblock lang=code] does not depend on the setting. Also hypothetically you could use (this already works):

Prints: [codeblocks] [gdscript lang=text] GDScript output. [/gdscript] [csharp lang=text] C# output. [/csharp] [/codeblocks]

Up the air now, but this addition has me question if the [codeblocks] + [gdscript]/[csharp] syntax should be replaced by [codeblocks] + [codeblock lang=gdscript/csharp]. Not to break what isn't broke, but just a thought.

Well IMO that would be quite verbose:

[codeblocks] [codeblock lang=gdscript] pass [/codeblock] [/codeblocks]

and hard to read, where s is the only difference between different tags.

It's a pre-existing issue with us having both [codeblock] and [codeblocks], but both are top-level tags, while [gdscript]/[csharp] are nested tags that further specify [codeblocks].

My proposal is instead to support both this:

[codeblocks] [gdscript] pass [/gdscript] [csharp] System.Collections.MadeUp.Pass<T>; [/csharp] [text] some text [/text] [/codeblocks]

and this:

[codeblock lang=gdscript] pass [/codeblock] [codeblock lang=csharp] System.Collections.MadeUp.Pass<T>; [/codeblock] [codeblock] some text [/codeblock]

Note that the two aren't equivalent - the first is a single code block with 3 tabs, the second is three code blocks each with different highlighting (with lang=text being inferred if not specified).

Mickeon · 2024-03-08T11:14:29Z

modules/gdscript/gdscript_parser.cpp

@@ -3504,21 +3505,23 @@ static String _process_doc_line(const String &p_line, const String &p_text, cons
 				from = rb_pos + 1;

 				String tag = line.substr(lb_pos + 1, rb_pos - lb_pos - 1);
-				if (tag == "code") {
+				if (tag == "code" || tag.begins_with("code ")) {


Maybe it would be better here to make a distinction between the initial "tag" and additional parameters, using something like String.split(). But then there's result += "[" + tag + "]"; below so I am not sure.

Mickeon · 2024-03-08T11:18:52Z

BTW I forgot we even had this feature, and I assume most users don't know it. We should probably expose this as a button in the EditorHelp that lets you enable GDScript and/or C# snippets (the latter being disabled on non-mono builds). Like it could be one button per language just reusing the language's script icon.

I had in my mind to eventually expose all Editor Help Settings as easily accessible preferences on the top-right, or something. There needs to be toggles to see deprecated/experimental class reference soon.

dalexeev · 2024-03-08T11:52:12Z

I don't think we actually have a C# syntax highlighter currently, so the addition here is theoretical.

I think for C# we use basic highlighting (EditorStandardSyntaxHighlighter, which gets keyword list, comment delimiters, etc. from ScriptLanguage).

Mickeon

If this PR was a post on a community forum it would get 500 upvotes and not a single comment, let alone one against it.

paulloz · 2024-03-08T12:54:29Z

I don't think we actually have a C# syntax highlighter currently, so the addition here is theoretical.

I think for C# we use basic highlighting (EditorStandardSyntaxHighlighter, which gets keyword list, comment delimiters, etc. from ScriptLanguage).

We do, but it is very rough. For instance, I couldn't tell you why one of the following is highlighted half-decently, and the other isn't.

Screenshots

raulsntos · 2024-03-08T19:34:15Z

@paulloz maybe related to New C# scripts use incorrect syntax highlighting in Godot's script editor #73438.

akien-mga · 2024-03-08T23:53:26Z

Thanks!

dalexeev added enhancement topic:editor documentation labels Mar 7, 2024

dalexeev added this to the 4.x milestone Mar 7, 2024

dalexeev force-pushed the editor-help-codeblock-syntax-highlighting branch from f77dc81 to 371617a Compare March 8, 2024 10:10

dalexeev marked this pull request as ready for review March 8, 2024 10:18

dalexeev requested review from a team as code owners March 8, 2024 10:18

dalexeev commented Mar 8, 2024

View reviewed changes

akien-mga reviewed Mar 8, 2024

View reviewed changes

editor/editor_help.h Show resolved Hide resolved

akien-mga reviewed Mar 8, 2024

View reviewed changes

editor/editor_help.h Outdated Show resolved Hide resolved

Mickeon reviewed Mar 8, 2024

View reviewed changes

Mickeon approved these changes Mar 8, 2024

View reviewed changes

dalexeev force-pushed the editor-help-codeblock-syntax-highlighting branch from 371617a to b926209 Compare March 8, 2024 12:47

akien-mga approved these changes Mar 8, 2024

View reviewed changes

akien-mga modified the milestones: 4.x, 4.3 Mar 8, 2024

dalexeev force-pushed the editor-help-codeblock-syntax-highlighting branch from b926209 to 6956013 Compare March 8, 2024 18:57

dalexeev force-pushed the editor-help-codeblock-syntax-highlighting branch from 6956013 to 225babc Compare March 8, 2024 20:48

Editor Help: Add syntax highlighting for code blocks

87718d2

dalexeev force-pushed the editor-help-codeblock-syntax-highlighting branch from 225babc to 87718d2 Compare March 8, 2024 21:05

akien-mga merged commit eccdf1a into godotengine:master Mar 8, 2024
16 checks passed

dalexeev deleted the editor-help-codeblock-syntax-highlighting branch March 9, 2024 00:40

Mickeon mentioned this pull request Mar 9, 2024

Use [codeblock lang=text] more often in class reference #89316

Merged

Mickeon mentioned this pull request Mar 26, 2024

Improve in-engine links that will open in a web browser godotengine/godot-proposals#9369

Open

dalexeev mentioned this pull request May 2, 2024

Update class reference and doc comment markup documentation godotengine/godot-docs#9313

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Editor Help: Add syntax highlighting for code blocks #89263

Editor Help: Add syntax highlighting for code blocks #89263

dalexeev commented Mar 7, 2024 •

edited

dalexeev Mar 8, 2024

dalexeev commented Mar 8, 2024 •

edited

akien-mga commented Mar 8, 2024

akien-mga commented Mar 8, 2024

Mickeon Mar 8, 2024

akien-mga Mar 8, 2024 •

edited

dalexeev Mar 8, 2024

akien-mga Mar 8, 2024

Mickeon Mar 8, 2024

Mickeon Mar 8, 2024

dalexeev Mar 8, 2024

akien-mga Mar 8, 2024 •

edited

Mickeon Mar 8, 2024

Mickeon commented Mar 8, 2024

dalexeev commented Mar 8, 2024

Mickeon left a comment

paulloz commented Mar 8, 2024

raulsntos commented Mar 8, 2024

akien-mga commented Mar 8, 2024

Editor Help: Add syntax highlighting for code blocks #89263

Editor Help: Add syntax highlighting for code blocks #89263

Conversation

dalexeev commented Mar 7, 2024 • edited

Choose a reason for hiding this comment

dalexeev commented Mar 8, 2024 • edited

akien-mga commented Mar 8, 2024

akien-mga commented Mar 8, 2024

Choose a reason for hiding this comment

akien-mga Mar 8, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akien-mga Mar 8, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Mickeon commented Mar 8, 2024

dalexeev commented Mar 8, 2024

Mickeon left a comment

Choose a reason for hiding this comment

paulloz commented Mar 8, 2024

raulsntos commented Mar 8, 2024

akien-mga commented Mar 8, 2024

dalexeev commented Mar 7, 2024 •

edited

dalexeev commented Mar 8, 2024 •

edited

akien-mga Mar 8, 2024 •

edited

akien-mga Mar 8, 2024 •

edited