Skip to content

Conversation

@Cykyrios
Copy link
Contributor

@Cykyrios Cykyrios commented Oct 7, 2025

Based on and supersedes #63079, this adds a few fixes and touch-ups to the work done by @Calinou.

This PR adds support for admonitions/callouts to the editor's help (and tooltips), as well as to the make_rst.py script. Four admonition types are supported: [note], [warning], [tip], and [important]. Nesting admonitions is supported by the editor but not supported by make_rst.py, and is not recommended.

image image

Note that these tags also work inline, but are obviously intended to be used as separate blocks. Multi-paragraph admonitions are also supported.

image

Converting all existing class reference XML files to this new format was removed from #63079, because of the noise it introduces in the PR, the conflicts after each rebase, and because actually converting the files is better left for a separate PR. At the time of this writing, the number of occurrences for each type of admonition is the following:

  • Regex used: \[b\](Note|Warning|Important|Tip) *: *\[/b\] *(.+?)\n
  • Notes: 3,382
  • Warnings: 127
  • Tips: 4
  • Important: 2
  • Replacing all occurrences can be done with [\L\1]\2[/\L\1]\n

@Mickeon
Copy link
Member

Mickeon commented Oct 8, 2025

This PR does not affect make_rst.py as of writing.

There's multiple ways we could go into, but I am still leaning into the least destructive one at the moment.
That would be, add compatibility code to handle existing "admonitions", so that even existing documentation can benefit from the extra styling. Fortunately, the worst case scenario if this isn't done, is that existing docs will look just as they did before, so it's not terrible already.

@Cykyrios
Copy link
Contributor Author

Cykyrios commented Oct 8, 2025

Oops, that's my bad, I forgot to include the changes I mentioned in #63079. I will add them as soon as I can (mypy is complaining so I will need to make some changes).

I'm personally leaning toward not changing the current behavior in this PR, but simply adding the new tags. This would avoid a styling discrepancy between the editor's bold Note: statements and the more colorful ones on the online documentation with.. note:: if we include compatibility code. When the new tags are actually by automatically converting everything, we can choose to keep some occurrences that wouldn't warrant the extra styling as they are.

Third party tools that rely one the current behavior will also only need to update once the XML files are converted, or to handle GDScript doc comments.

@Cykyrios Cykyrios requested a review from a team as a code owner October 8, 2025 11:50
@Mickeon Mickeon requested a review from Calinou October 8, 2025 17:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants