Skip to content

Add support for classref admonitions#12017

Open
Cykyrios wants to merge 1 commit into
godotengine:masterfrom
Cykyrios:classref-admonitions
Open

Add support for classref admonitions#12017
Cykyrios wants to merge 1 commit into
godotengine:masterfrom
Cykyrios:classref-admonitions

Conversation

@Cykyrios

Copy link
Copy Markdown
Contributor

godotengine/godot#111375 adds support for admonitions in the editor, but there were concerns about the size of Sphinx admonitions for the online documentation, especially since some class properties/methods have multiple consecutive notes. That PR now generates a special rST directive, which this PR adds support for, via a custom extension and some CSS.

The extension itself was made using some AI help, maybe the ClassrefAdmonitionHTMLTranslator class warrants a closer look, and the global visit_paragraph and depart_paragraph functions that are linked to it. The rest looks alright to me and not unlike what I could see in other extensions.

The following screenshot is from the Resource page, with all Note:, Warning:, Tip:, and Important: admonitions converted using godotengine/godot#111375:
image
Here are all the available types of admonitions:
image

If someone knows how to get the correct icons from admonitions, I'd like to have those instead of a generic admonition icon.

@akien-mga

Copy link
Copy Markdown
Member

FYI, it seems you used your no-reply email from GitLab instead of GitHub for your godot-docs clone, so the commit doesn't appear linked to your GitHub account.

@Cykyrios Cykyrios force-pushed the classref-admonitions branch from 634d425 to f516bf3 Compare May 26, 2026 19:24
@Cykyrios

Copy link
Copy Markdown
Contributor Author

Fixed my git config and increased color saturation, also using okhcl color space for mixing colors instead of srgb. This makes the admonitions pop a bit more:
classref_admonitions_dark
classref_admonitions_light

@Cykyrios Cykyrios force-pushed the classref-admonitions branch from f516bf3 to 80edf43 Compare May 27, 2026 05:32
@Cykyrios

Copy link
Copy Markdown
Contributor Author

Fixed saturation being applied twice to the title, and made saturation theme-dependent. @Mickeon mentioned all existing admonitions using the same icon, so this PR will not try to get the "right" icon for each type.

classref_admonitions_dark classref_admonitions_light

@Mickeon Mickeon left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do approve this in principle as I have godotengine/godot#111375 already. I can't speak much about the code required for it, but as we discussed the styling it's currently pretty good.

In due time we should also update the contributors documentation to mention these admonitions.

Comment thread _extensions/classref_admonitions.py
@Cykyrios Cykyrios force-pushed the classref-admonitions branch from 0d27adb to c10ae64 Compare May 27, 2026 11:46
@Mickeon Mickeon added enhancement area:class reference Issues and PRs about the class reference, which should be addressed on the Godot engine repository labels May 27, 2026
@Cykyrios

Copy link
Copy Markdown
Contributor Author

I cleaned up the unused icon and paragraph functions in the python file, and added icons using the SVG files from the editor (the same ones as godotengine/godot#111375). They can be added to standard admonitions in a separate PR if needed.

classref_admonitions_dark classref_admonitions_light
@AThousandShips AThousandShips added the waiting on pr merge PRs that can't be merged until an engine PR is merged first label May 27, 2026
@Cykyrios

Copy link
Copy Markdown
Contributor Author

Just a quick note on the waiting on pr merge PRs that can't be merged until an engine PR is merged first label, this is actually the other way around: this PR should be merged first, so that godotengine/godot#111375 won't generate unsupported rST (for methods returning PackedArrays only if I'm not mistaken).

@Calinou Calinou left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally on Firefox 150 and Chromium 148, it works as expected.

color-mix is well-supported in CSS overall (it's considered Baseline now).

@mhilbrunner mhilbrunner removed the waiting on pr merge PRs that can't be merged until an engine PR is merged first label Jun 4, 2026
@mhilbrunner

Copy link
Copy Markdown
Member

Left a note on godotengine/godot#111375 that this PR is good to go if a decision is made to merge the feature.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:class reference Issues and PRs about the class reference, which should be addressed on the Godot engine repository enhancement

6 participants