Improved font outline docs.

Specify that the thickness is in pixels, and added example to render
outlined text.

Author: cherez

docs/reST/ref/font.rst

@@ -309,15 +309,36 @@ solves no longer exists, it will likely be removed in the future.
 
    .. attribute:: outline
 
-      | :sl:`Gets or sets the font's outline value`
+      | :sl:`Gets or sets the font's outline thickness (pixels)`
       | :sg:`outline -> int`
 
       The outline value of the font.
 
       When set to 0, the font will be drawn normally. When positive,
-      the text will be drawn as a hollow outline. This can be drawn
-      underneath unoutlined text to create a text outline effect. Larger values
-      produce a thicker outline. Negative values are not valid.
+      the text will be drawn as a hollow outline. The outline grows in all
+      directions a number of pixels equal to the value set. Negative values
+      are not allowed.
+
+      This can be drawn underneath unoutlined text to create a text outline
+      effect. For example: ::
+
+          def render_outlined(
+              font: pygame.Font,
+              text: str,
+              text_color: pygame.typing.ColorLike,
+              outline_color: pygame.typing.ColorLike,
+              outline_width: int,
+          ) -> pygame.Surface:
+              old_outline = font.outline
+              if old_outline != 0:
+                  font.outline = 0
+              base_text_surf = font.render(text, True, text_color)
+              font.outline = outline_width
+              outlined_text_surf = font.render(text, True, outline_color)
+
+              outlined_text_surf.blit(base_text_surf, (outline_width, outline_width))
+              font.outline = old_outline
+              return outlined_text_surf
 
       .. versionadded:: 2.5.6
 

src_c/doc/font_doc.h

@@ -17,7 +17,7 @@
 #define DOC_FONT_FONT_STRIKETHROUGH "strikethrough -> bool\nGets or sets whether the font should be rendered with a strikethrough."
 #define DOC_FONT_FONT_ALIGN "align -> int\nSet how rendered text is aligned when given a wrap length."
 #define DOC_FONT_FONT_POINTSIZE "point_size -> int\nGets or sets the font's point size"
-#define DOC_FONT_FONT_OUTLINE "outline -> int\nGets or sets the font's outline value"
+#define DOC_FONT_FONT_OUTLINE "outline -> int\nGets or sets the font's outline thickness (pixels)"
 #define DOC_FONT_FONT_RENDER "render(text, antialias, color, bgcolor=None, wraplength=0) -> Surface\ndraw text on a new Surface"
 #define DOC_FONT_FONT_SIZE "size(text, /) -> (width, height)\ndetermine the amount of space needed to render text"
 #define DOC_FONT_FONT_SETUNDERLINE "set_underline(bool, /) -> None\ncontrol if text is rendered with an underline"