Skip to content

Docs: Replace "Note:" and "Warning:" blocks with admonitions in RST files - #122080

Open
Meorge wants to merge 1 commit into
godotengine:masterfrom
Meorge:docs/theyre-called-admonitions-apparently
Open

Meorge wants to merge 1 commit into
godotengine:masterfrom
Meorge:docs/theyre-called-admonitions-apparently

Conversation

@Meorge

@Meorge Meorge commented Aug 4, 2026 •

Copy link
Copy Markdown
Contributor

What problem(s) does this PR solve?

I thought I'd remembered writing a proposal for this some time ago, but couldn't find it tonight (or another proposal that matches it). If need be I can write a proposal for it soon, to go alongside this PR.

Additional information

This PR adds an extra processing step to the conversion from the XML class reference files to RST documents, so that [b]Note:[/b] and [b]Warning:[/b] blocks are now placed in admonition blocks ([note], [warning], etc). These help them stand out more to readers (especially important for warnings).

Before After
CleanShot 2026-08-03 at 22 05 04@2x CleanShot 2026-08-05 at 09 21 48@2x

Note that localization is not currently supported; as you can see in the PR changes, the strings "Note:" and "Warning:" are hardcoded. I don't think that this should break anything in localized versions - they should just appear the same as before. But for this to support localized versions of the class reference, we'll need to find the corresponding strings in each language and replace them in the regex pattern here.

@Mickeon

Mickeon commented Aug 4, 2026 •

Copy link
Copy Markdown
Member

This PR is more like "compatibility" glue, in comparison, but it may be redundant if we end up replacing all pseudo-admonitions in the future either way.
Also the default look of the admonitions is unsuitable for the class reference due of how many there can be, which is why godotengine/godot-docs#12017 also exists.

@Meorge

Meorge commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for pointing that out! I agree the default admonitions are definitely on the big side especially when there are several in sequence. The PRs you linked sound like they tackle the problem well and have good approval, so I'll close this PR for now and put my support behind those ones instead.

@Meorge Meorge closed this Aug 4, 2026
@Mickeon

Mickeon commented Aug 4, 2026 •

Copy link
Copy Markdown
Member

Mind you, I'm not necessarily dismissing this PR. A similar idea may even be the better option in the near future because a full replacement (for translations, too) is a big undertaking (but we've done it before)

@Meorge

Meorge commented Aug 4, 2026

Copy link
Copy Markdown
Contributor Author

Alright, I will re-open it then just in case, but still see what I can do to support the other PR. Thank you for the clarification 😄

@Meorge Meorge reopened this Aug 4, 2026
@Cykyrios

Cykyrios commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Do feel free to use the regex I mentioned in #111375, as it also includes [b]Tip:[/b] and [b]Important:[/b] (which are on the rare side compared to Note and Warning). This PR could indeed be a good candidate for converting all of them once #111375 is merged, especially since it avoid having to be synced every now and then, but it should use the classref_ prefix for RST directives.

Once #111375 is merged, and if/when we decide the new "classref admonitions" are the way to go, we'll need to ask contributors to start using the new format as well.

In the long run, the spots where these show up in the XML documentation should be moved from [b]Note:[/b] to [note] and so on. But for now, this should convert the existing ones to the new appearance.
@Meorge
Meorge force-pushed the docs/theyre-called-admonitions-apparently branch from 1c6416d to b02283f Compare August 5, 2026 16:11
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.

4 participants