Add an XML schema for documentation

[Calinou]

master version of #59213.

This makes it easier to spot syntax errors when editing the class reference. The schema is referenced locally so validation can still work offline.

Tested with the vscode-xml Visual Studio Code add-on.

[follower]

PS: Is there a way to forbid an element from containing anything (even text)? This would be very nice to have for <argument> elements, as they can't have a description.

Based on a very cursory web search, It seems so, with a couple of variations:

• https://stackoverflow.com/questions/20751782/define-an-xml-element-that-must-be-empty-and-has-no-attributes
• https://stackoverflow.com/questions/45077301/xsd-how-to-describe-an-element-so-it-can-have-no-value
• https://www.w3schools.com/xml/schema_complex_empty.asp
• https://www.ics.uci.edu/~alspaugh/cls/shr/xmlSchema.html#SimpleAndComplexContent

Simplest option seems to be:

<xs:complexType/>

[Calinou]

I updated the pull request to add the XML schema mention in the root tag when using --doctool.

[fire]

I support using existing xml tools to validate our xml variation. Xml validators allows tools to check our xml docs. We didn't need validators at first, but with the growth of Godot Engine scope and scale tool validators help.

[akien-mga]

I don't see code added to DocTools to actually write the XML schema to the header in new files, how does it work?

[Calinou]

I don't see code added to DocTools to actually write the XML schema to the header in new files, how does it work?

I forgot to readd that part while remaking this PR from scratch, and I no longer have the original code around 🙁

[akien-mga]

Some of your old commits referenced above in force push notifications haven't been GC'ed yet:

https://github.com/godotengine/godot/blob/f4dbc64abbf95f00f47e23ace284855a37004f29/editor/doc_data.cpp#L1068-L1073

Could use contains() instead of find() now.

[akien-mga]

Some XMLs have the wrong path: https://github.com/godotengine/godot/runs/5187484781?check_suite_focus=true

[Calinou]

Some XMLs have the wrong path: godotengine/godot/runs/5187484781?check_suite_focus=true

Fixed. I suppose this happens because I ran --doctool with the Mono module disabled, and the fallback text server is disabled when the advanced text server is enabled.

[akien-mga]

There's a style issue in the DocData changes.

[Calinou]

We could make the CI output quieter by using xmllint's --quiet option, but this option isn't available in the version that ships with Ubuntu 18.04 🙁
Redirecting stdout to /dev/null doesn't suppress successful validation messages, as they go to stderr.

--quiet works with libxml 20912 from the Fedora 34 repositories. It suppresses messages for valid XML files while keeping messages for invalid XML files.

[akien-mga]

Thanks!