From d9add84222c3e54dcba44a1dd6b9c71e503467a5 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Thu, 10 Sep 2026 01:16:24 +0200 Subject: [PATCH] Document admonitions in GDScript documentation comments --- .../gdscript_documentation_comments.rst | 37 ++++++++++++++++++ .../gdscript/img/admonition_important.webp | Bin 0 -> 1432 bytes .../gdscript/img/admonition_note.webp | Bin 0 -> 1046 bytes .../gdscript/img/admonition_tip.webp | Bin 0 -> 994 bytes .../gdscript/img/admonition_warning.webp | Bin 0 -> 1406 bytes 5 files changed, 37 insertions(+) create mode 100644 tutorials/scripting/gdscript/img/admonition_important.webp create mode 100644 tutorials/scripting/gdscript/img/admonition_note.webp create mode 100644 tutorials/scripting/gdscript/img/admonition_tip.webp create mode 100644 tutorials/scripting/gdscript/img/admonition_warning.webp diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst index 89e62de592c..fa270ebda13 100644 --- a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst +++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst @@ -363,3 +363,40 @@ the ``lang`` attribute. Currently supported options are: - ``[codeblock lang=text]`` disables syntax highlighting; - ``[codeblock lang=gdscript]`` highlights GDScript syntax; - ``[codeblock lang=csharp]`` highlights C# syntax (only in .NET version). + +Admonitions +----------- + +Since Godot 4.8, documentation comments can contain *admonitions*. These are +displayed as separate paragraphs with their own highlighting. You +can use admonitions to bring particular attention to a section of your +documentation, such as warnings, tips, or notes. + ++----------------------------------+-----------------------------------------------+------------------------------------------+ +| Tag | Example | Result | ++==================================+===============================================+==========================================+ +| ``[note]`` ``[/note]`` | ``[note]This is a note.[/note]`` | .. image:: img/admonition_note.webp | ++----------------------------------+-----------------------------------------------+------------------------------------------+ +| ``[warning]`` ``[/warning]`` | ``[warning]This is a warning.[/warning]`` | .. image:: img/admonition_warning.webp | ++----------------------------------+-----------------------------------------------+------------------------------------------+ +| ``[important]`` ``[/important]`` | ``[important]This is important.[/important]`` | .. image:: img/admonition_important.webp | ++----------------------------------+-----------------------------------------------+------------------------------------------+ +| ``[tip]`` ``[/tip]`` | ``[tip]This is a tip.[/tip]`` | .. image:: img/admonition_tip.webp | ++----------------------------------+-----------------------------------------------+------------------------------------------+ + +By convention, admonitions should always be placed at the end of the +description. Multiple admonitions can be used in a single description (including +admonitions of the same type): + +:: + + ## Description of the example property. + ## [note]This is a note.[/note] + ## [warning]This is a warning.[/warning] + ## [important]This is important.[/important] + ## [tip]This is a tip.[/tip] + @export var example = "" + +Admonitions should be used sparingly, as they can make the documentation harder +to read if overused. They are best used to highlight important information that +the user shouldn't miss. diff --git a/tutorials/scripting/gdscript/img/admonition_important.webp b/tutorials/scripting/gdscript/img/admonition_important.webp new file mode 100644 index 0000000000000000000000000000000000000000..ffcafbd3d2487fafba62422fca2ec4bd7bb566c7 GIT binary patch literal 1432 zcmV;J1!wwFNk&GH1pok7MM6+kP&iD31pojq{y+!-w+E?>BtcTRpUYwSV_E?BJP0$b zyDrUAa1=?Bt#me@GY0T40~Ory@!q4|Mv^2&Sv+Rozgg&L&#A}EKY^r8g1g6fzmJdz z2?RpIY7$6*gz~3kA%m3F9&PNgs61Wde*k_2da{)TKh!we**abzePU#=&iRt`n=E|wQt_~ z!0Vge+0>NRZofj!WxIwYAvP7G=lZfPB(D!amrwt?ef$0gAAA5GeDJ~hKm2mWDA`|? zr3Oy&_3hjDL}K5*ed{69m9z|hdu332<2c}%!v-Jj)xC3l8Ai5e(LHL0*a zH1&lpU}(gK*vJhz*eof=UmrUA#JAhA&vfUdSW9YwsmO%;maH1ELyB|jK^{znq`S{8 z2vz2d1Za*OOpp!xF#jU4h zOmcL0Y~AhAS4P%Z@2-cT2YXv}zjZqsn3>Cao7P5Hl5lNA`+P06xN-JeA@@dfJ(yMn zL-!Uno|3kl3e(iPzQ5jf_PTF}vQ)8j)+idQrI^wP%Eo9X4W-G{OwdwHX>Qi6j8QT$ zWnX`?g=sFP)SJ%I04hrjU}e%6Kd2^D(NHggRRZcXbF$?Y(5{N3Rgg7p69gsB#n2_7 zLdIzFrJ2BZRbh#{9FR>TAbbC^kky)sq20jtyU@87q3?CqCS=C{e6zA5Xymob@lr`C66n-W?(g#pP8pdL_ugs+8#+=UQt6aO2{T38A;M!J>?1y%t)VvElKVuDLsCOSf^? zlbls>ujoj#%ng3wyEi}Z`p%C8>`wDbsV}zxT(fRlVOvXJ$JD232Wb3a>eC5_e4y>M zXCcOlq%i?v_%$nfM{yhkFMaatp&1;2aZBUl4-^HMc-y)^%jKZW?X)gTc$oTX%g4@` m8lIY`X6!uwQ25J_-+1GbuL=@qQ+N2CXlM+-#eenvS3CgLr^`VA literal 0 HcmV?d00001 diff --git a/tutorials/scripting/gdscript/img/admonition_note.webp b/tutorials/scripting/gdscript/img/admonition_note.webp new file mode 100644 index 0000000000000000000000000000000000000000..4bb19f70bc601529a9d4094ef8618830c4a7fafb GIT binary patch literal 1046 zcmV+x1nK)yNk&Ev1ONb6MM6+kP&iBh1ONap{y+!-pXQ)#BSETrIG#Vwnc3%HAZ^=F zv+Fp5wr!iLv(xze8%WzmzFoOw1Ggiub`f4){NZW_u5Ma{y%9wr$$cytiW8DBCt~lCo{vwi(;D zZQGuobobdo(_6KO{!ak@|JVLOdRtriJ-g|eM;nE$dz5_1EdWf&)8k^0;!JF&yGWH0 zGLrr6>!&Q5VJZ&qk}1?1h12XBCC|NkpYrP7y_;na@Np#D@)nOb10J6w>{>|@AjuXR z3Emw?06aJkfYbyydEBE6Zz-j*$5p}NRb^k{Z5_NP$@hRJv8&;m6EN5N_-L#N>@K|o zApQs7@~5pMe70ya-GQ}nJ&j*X70zdL*S5co<9Ll|q<78Pgt8DO{J)@C*f3FXB3Do&np4;Lp3?$t8 zytf>v{wuo1H#^TZe^p93x$+%%0GkGV_g<{b(6e64$14m~(Jhy}0{WLvXdMDT(5w`; zaEQB&wQjO+DUOocaGG6!ehVMLIF(P~)&6BPE&)2_p9GHF57_R}mpDv2VE!u6Y%c&0 zT9r-$s^SkodXx&7Gk6vTJPv5M9#CfnPeRf7z+w}vX#N9G#8;wqAMf49w%ooi|U}I9OggXG=P|V>Lt>3Yt z-xM26WOwDR%it7?TX`BW^afDG*P;y^KD2l5-o2Xf0L)nOYk0m4V6-*8R##9F?+#oX znJtfM#e0k16)h2}Co;PhnMNxqRU*mLxXr$$I6`j6Q4UzZu!EO?E6;afuJ`dVa(!Y7 zxbld^>Kg!#(^*Sr_%eW>BSU7S3Ya~34thKZc=XQ#uzne!XFXwI_b?TQwn7RE2DOay z$rjQFm``@U#09dfhQnU?&Ym%H=nB_(#dSGLX!v^jsftXM781)(?DI3DWyUf*5RabW1>wN}<^}0-0*wZR%+J+I}l@_etR`nI#(*ba$qW=%znb_GDy94lQ z|2#%m8QswtwipsPmfhR<#U4Uu|E}8C=SKmX;=AiVSOVBs(7zK#&no%~Z>WJ!l{OO> QZ11GBv?SlM!GCZA0K*IQl>h($ literal 0 HcmV?d00001 diff --git a/tutorials/scripting/gdscript/img/admonition_tip.webp b/tutorials/scripting/gdscript/img/admonition_tip.webp new file mode 100644 index 0000000000000000000000000000000000000000..dbca6d2d88613136f797e1fb2070377e1435b792 GIT binary patch literal 994 zcmV<810DQQNk&H60{{S5MM6+kP&iD@0{{Ro{y+!-*XFowBu6UMx+pgPybkx<-+9}G zyWSuiv~46vaSz9ne!x2r8cA{_WwegQ^QY(i&-DB&1P}lbXf)Q}QwpM>=+Htj00kI> z0VswyD1ZVe3WPuiM1fG6w2K%vD8T3l0}u#70f1r{V1PgYT_!OM0(81SA%-z*P{3dy zhGKvLfI%@7hS5tF8wN!%3<@v|Fc=g=*iDQZfMO7c!a$bq0RV^b-|M3$4MSm20A<(! zgMsv^f&zY}eW?Gl+?7^ZkB(}km6BFUMLM?ol&FrBY8`u*j+EQ`_vt$M7NnIIS#i}7 z$*t=8mV;+?t6DlZ-i}yXU;MK5MXtKA^(~Mn*|upr^Vzm-+qV5)Y}>YNBKki8`2XMc4=$ZLb?M;;Iq}s-KRnM)G4APC0v{6RoA*$elxPx;#jyPX zx5ERzB)2(Md%4ZA>i7H@6CQgZL1*DEKPgt(+1ZO)va_>;mDsJX_>$z!AzDcx7a)0a zi0XYf&4ee|>5m*38X8WbwT6a804le3?QIg6joQ_@tzL&Sk%*2Ukvxz{ zL5sT%3^!7%i;SJnxS@-i?25Eq-8=hehbd-IhlHc+stPx@*l_f=Y{*Prv(H39LI2R$ zy51Vz!q$eAAymR~t)q+(!Hz-U<;~O7>Lk1H_8Mb1ba9)pGtxSIkxEp8tmbJFC;;%H zB90y90@i893MOv>km$*aivqBGJ_jk}0>KynMdYDcw_tGnhA!?fZOj3%nWjLw=m-F` z4dCeQ+FE1>p++%{i!g#h+qkj=DHXaBxsTUSc(27vZPm3qV&yARxDnop%I0ze_2drNsu5luW5VNaAZI5ZQIiHtkrFf3P!ir zClBZv$FXc(m6^Bdpun|%RI*^xl1*kpLVZjTV-+5@H5m4G3uS)pz`10w~SDt)?^p!Lb Q-||HAz<2JizJJUE06%Z#{{R30 literal 0 HcmV?d00001 diff --git a/tutorials/scripting/gdscript/img/admonition_warning.webp b/tutorials/scripting/gdscript/img/admonition_warning.webp new file mode 100644 index 0000000000000000000000000000000000000000..89374ef59e88354d788065601df2f87b4596edc4 GIT binary patch literal 1406 zcmV-^1%difNk&F?1pok7MM6+kP&iC!1pojq{y+!-kLRe7BuA>O*OFNNwD$ZF@cypN zP;k^pk|R~rZ?zbfKPtZm!CNtkBuP={fsFI-=}hozasJV^ZJRx5shlxSM*t8431tEb z5(I>RAV>fblq3P+FeCs80RaF)0r7VvjS;wjWZfTDA?_j^nbO&^{Wn(`;75tP+~cC) zlJP%KiE|N102cuOmo|0K-nP2@y7Gnc#s2t#qi{dt$z>XLyZ!O}PS0<5x)$%x^!^Qx z|MdP0w^z4aF86o0%(vI4J6?Xz{{Z^iwjFPzE5+EhZQHhO+qP}nD8{x?PHp8LTl+WU z`@WfEw!1&=9ufVY0RGo;<6$2E3etZ3l*US3sXK5@!9ZiFs}r&$Ymk%b$#f}m{Y{F6 zO!<}NemVX;+qJ`g)YsRqzgcmQ)(XgGmrBAk*>gF;w(ntCC*|zix$}Xj&Ye3~vXcMW z;9r?~F3X?C{`G&-&sVQszx>MrhjbNMOBw`+be&(dS#i;&Avjw22m1Lny#8Wkyi&5T zP zfw}j3J$pe@)i@mccqHJv6@1r>d=_=E2#|e4Nc75f%IPBCUpu`1VWG0rl(U+tN0gP? za8&V^qjlRIFFlpr;ZkCpG{fwYJyJRa&Fr$r-;Yyo{B-CyL|hr#>sC}=gQ5w$n{^A= zWu=FGPQx)NBaHS%Pi#3${SENh58Vt+jMK{2Lqa#h+{l~#o6%I42G(A!Rwj>j z)$izk9&G1=NB1~%!&TD0F?yTE%od^<84^__K?MdYIZKuWdrDDBs*RW8o7+5*e6nOX zt-EF+#aSrj!AFk^d2Et;vp9P2Z%}zCsXhihl^ZJ6wX*IG(6ppcqq@MUJw}tFJy^Fn zp(cG(a#E%fFg+aR+6x0sH4tnM)|$CPALXN?>Vex;SNZzd==C=7?eyp)H*As4*j&Owg(pTH5wFf z+Niwh^Q5QuRJQm6WUJZ3M=&=KgR;QBgC;wHs;bVaCjjGJ^2EnZq<)E)XO!E6l_k!t0ZIs(bR&EFwnngIqh}G1&@KRxNg(ap>+MpI=-2VpdYxp*}R$ z!Duz4wGu}a$?OX0rQwi6t^paFUk&oG0=fEx>^3N2U!4PXnyvEgcZ*sv6;u(P`<8&= z&Rh4`VU%lpf9(hkuYZ{ET+u2-`h*z8rDK#H*y!vE+|rG#%y;Otr-qa2O$7R@kcD1d zfz6K$ny3P#du-M!cH<)4!dCl%yL}X}&3S!P8}N0==d`!h-kEKd9s=Idaj0R}os*&Q zuFy-0@_Uk`-uUT|liF)V%R$et+bk@J9ou3`!ZL##(cT@qc?X)MkBw;pJ7d=XXP*sd zw;{lJ>28ON>9*&-axz6-ob}$o^n+O+X+1DgngaB@pK!f?h$}Gge!}HSG3w5u=)q2+ z-_7`tO?j~3vEW(aW9LT M9?bAaef|?202N`;4FCWD literal 0 HcmV?d00001