Documentation: Add support for deprecated/experimental messages

[dalexeev]

Add support for deprecated/experimental messages to core and GDScript. See:

• Add @deprecated annotation to GDScript godot-proposals#6559
• Add @deprecated annotation godot-proposals#7622

## my_func desc.
## @deprecated: Use [method another] instead.
func my_func():
    pass

• Bugsquad edit, fixes: "Deprecated" needs to be more visible in the documentation godot-docs#7900

• Production edit: closes godotengine/godot-roadmap#71

[YuriSizov]

This would be a breaking change for the XML format. We should find a way to avoid that.

[dalexeev]

We can use two attributes, bool and string, just like in DocData structures. But it's less compact. Or we can add compatibility code for the old boolean attributes, which will allow the old XMLs to be read, but on write they will be saved in the new format. It's funny if we deprecate the is_deprecated attribute.

[raulsntos]

I love this, we've been generating generic messages like This method is deprecated in the generated C# API and now we'll be able to provide something more informative.

I noticed there were some empty deprecation messages. Should we try to avoid empty messages or is it intended that some messages will be empty? We can still provide the generic message in C# in these cases, but I think it'd be better to provide a better message. I'm not suggesting to fill all the messages in this PR, it could be a follow-up.

I'm not sure how useful it is for experimental API though, it seems all the messages are empty in this PR. I also don't know what we would write here other than a generic This API is experimental and may change in the future. We also wouldn't be able to use these messages in C#, the [Experimental] attribute doesn't allow providing a message, but that shouldn't block this if it's still useful.

[raulsntos]

I think there was someone asking recently why this class was deprecated, worried that it will be removed without an alternative. Maybe we could add a message here that clarifies that a replacement will be provided in the future?

[akien-mga]

CC @godotengine/animation

[dalexeev]

I noticed there were some empty deprecation messages. Should we try to avoid empty messages or is it intended that some messages will be empty?

I think so, but I've left the messages empty for now. We should also think about default messages. Now I've added a neutral "This ... may be changed or removed in future versions.", but this should probably be different for Deprecated and Experimental and for engine and user code.

I'm not sure how useful it is for experimental API though, it seems all the messages are empty in this PR. I also don't know what we would write here other than a generic This API is experimental and may change in the future.

Probably yes, although I think that sometimes we can indicate problems when using the experimental API:

[dalexeev]

• See Doctool: Remove version attribute from XML header #79092.

[dalexeev]

Is there a way to use color in RST? This will probably require some changes to the site so that we can use:

:red:`Deprecated:"` Message.

or

.. deprecated:: Message.

Now it looks like this:

I only added this to the descriptions, not to the overviews.

[Calinou]

rST doesn't support arbitrary colors (aside of raw HTML tags). You could use the .. danger:: adominition though, which appears in red.

See also #63079.

[dalexeev]

How to use color in text with ReStructured Text (rst2html.py) or how to insert HTML tags without blank lines?

[AThousandShips]

LGTM style and code wise

[Calinou]

Tested locally (rebased on top of master f317cc7), it mostly works as expected.

I can't get the deprecated/experimental reason messages to show up though:

extends Node2D

## Description.
##@deprecated: Test reason
var var1

##@experimental: Test reason 2
var var2

# Test comment (not a docblock).
##@deprecated: Test reason 3
func one() -> void:
	pass


##@experimental: Test reason 4
##Description.
func two() -> void:
	pass

[dalexeev]

@Calinou Looks like you were testing an older version:

[dalexeev]

I have completed self-review and testing. This initially small PR grew into a significant EditorHelp refactoring:

• Add missing XML escaping in DocTools.
• Rename "Theme Item" to "Theme Property" in various make_rst.py and editor_help.cpp messages for consistency. This does not break compatibility, the [theme_item] tag is left unchanged.
• Fix a bug with [theme_item] navigation for external classes.
• Unify blank lines for all Editor Help sections.
• Fix theme property anchors.
• Replace find() with find_char() for optimization.
• Improve grouping of push_*() and pop() calls, add comments for consistency.
• Fix usage of text append methods:
  • class_desc->add_text() - Used to add text "as is".
  • class_desc->append_text() - Used to append text that is guaranteed to contain only standard BBCodes.
  • _add_text() - Used if the text can contain custom EditorHelp markup.
• Add missing _fix_constant() and value color.
• Improve detection of multiline descriptions for constants and enum elements.
• Improve link for property overrides.

[akien-mga]

Looks great to me overall!

[akien-mga]

CC @godotengine/animation

[akien-mga]

We should probably find some consensus on how to documentation deprecated and experimental methods/properties, and apply it throughout the codebase (cc @godotengine/documentation).

Notably, how to document a method/property when it's deprecated because:

• It doesn't do anything and we're just keeping it to avoid breaking API compat
• It still does something but was replaced by a new method/property which should be referenced
• It still does something but is no longer supported, and no alternative is given

We can now put information in the deprecated message, but there's still the main description to deal with. What should it contain? Should it be kept empty if all the relevant info is in the deprecation message? If so, should we change doc/tools/doc_status.py so it considers an empty description of a method/property with a deprecated message as fully documented?

[Mickeon]

I was taking a look. In my opinion, to make it extremely short:

• The deprecated/experimental message should explain "why" and/or provide the better alternative(s);
• The description should explain "what". Very, very briefly.
  • I can't think of exceptions. Not saying what something is/was feels wrong to me.

_{Also these messages are not translatable now, are they?}

[dalexeev]

Also these messages are not translatable now, are they?

Yes, after merging this PR, some changes are needed in extract_classes.py.

As for the docs, I agree with you, but I think that in any case we will need a follow-up PR for adjustments. However, I'm ready to apply suggestions that we are already confident about.

[Mickeon]

I don't mind scouting across the class reference a second time as some form of standardization, post-merge. I got nothing better to do...

[akien-mga]

Thanks!