Merge pull request #2346 from rethanon/main

Add Named Colors to docs for pygame.draw and pygame.Surface

Author: Starbuck5

docs/reST/ref/draw.rst

@@ -23,10 +23,9 @@ bounding box that encloses the affected area.
 All the drawing functions accept a color argument that can be one of the
 following formats:
 
-   - a :mod:`pygame.Color` object
-   - an ``(RGB)`` triplet (tuple/list)
-   - an ``(RGBA)`` quadruplet (tuple/list)
-   - an integer value that has been mapped to the surface's pixel format
+   - a :mod:`pygame.Color` object, or a type (apart from ``int``) that can be passed to
+     its constructor
+   - an ``int`` value which must be mapped to the pixel format of the surface
      (see :func:`pygame.Surface.map_rgb` and :func:`pygame.Surface.unmap_rgb`)
 
 A color's alpha value will be written directly into the surface (if the
@@ -53,7 +52,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param Rect rect: rectangle to draw, position and dimensions
    :param int width: (optional) used for line thickness or to indicate that
       the rectangle is to be filled (not to be confused with the width value
@@ -111,7 +110,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param points: a sequence of 3 or more (x, y) coordinates that make up the
       vertices of the polygon, each *coordinate* in the sequence must be a
       tuple/list/:class:`pygame.math.Vector2` of 2 ints/floats,
@@ -159,7 +158,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param center: center point of the circle as a sequence of 2 ints/floats,
       e.g. ``(x, y)``
    :type center: tuple(int or float, int or float) or
@@ -218,7 +217,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param Rect rect: rectangle to indicate the position and dimensions of the
       ellipse, the ellipse will be centered inside the rectangle and bounded
       by it
@@ -259,7 +258,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param Rect rect: rectangle to indicate the position and dimensions of the
       ellipse which the arc will be based on, the ellipse will be centered
       inside the rectangle
@@ -309,7 +308,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param start_pos: start position of the line, (x, y)
    :type start_pos: tuple(int or float, int or float) or
       list(int or float, int or float) or Vector2(int or float, int or float)
@@ -361,7 +360,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param bool closed: if ``True`` an additional line segment is drawn between
       the first and last points in the ``points`` sequence
    :param points: a sequence of 2 or more (x, y) coordinates, where each
@@ -482,7 +481,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param start_pos: start position of the line, (x, y)
    :type start_pos: tuple(int or float, int or float) or
       list(int or float, int or float) or Vector2(int or float, int or float)
@@ -516,7 +515,7 @@ object around the draw calls (see :func:`pygame.Surface.lock` and
    :param Surface surface: surface to draw on
    :param color: color to draw with, the alpha value is optional if using a
       tuple ``(RGB[A])``
-   :type color: Color or int or tuple(int, int, int, [int])
+   :type color: Color or string (for :doc:`color_list`) or int or tuple(int, int, int, [int])
    :param bool closed: if ``True`` an additional line segment is drawn between
       the first and last points in the ``points`` sequence
    :param points: a sequence of 2 or more (x, y) coordinates, where each

docs/reST/ref/surface.rst

@@ -248,10 +248,10 @@
       entire Surface will be filled. The rect argument will limit the fill to a
       specific area. The fill will also be contained by the Surface clip area.
 
-      The color argument can be either a ``RGB`` sequence, a ``RGBA`` sequence
-      or a mapped color index. If using ``RGBA``, the Alpha (A part of
-      ``RGBA``) is ignored unless the surface uses per pixel alpha (Surface has
-      the ``SRCALPHA`` flag).
+      The color argument can be an ``RGB`` sequence, an ``RGBA`` sequence,
+      a string (for :doc:`color_list`), or a mapped color index. If using ``RGBA``,
+      the Alpha (A part of ``RGBA``) is ignored unless the surface uses per pixel
+      alpha (Surface has the ``SRCALPHA`` flag).
 
       .. versionaddedold:: 1.8
          Optional ``special_flags``: ``BLEND_ADD``, ``BLEND_SUB``,
@@ -285,13 +285,14 @@
    .. method:: set_colorkey
 
       | :sl:`Set the transparent colorkey`
-      | :sg:`set_colorkey(Color, flags=0) -> None`
+      | :sg:`set_colorkey(color, flags=0) -> None`
       | :sg:`set_colorkey(None) -> None`
 
       Set the current color key for the Surface. When blitting this Surface
       onto a destination, any pixels that have the same color as the colorkey
-      will be transparent. The color can be an ``RGB`` color or a mapped color
-      integer. If ``None`` is passed, the colorkey will be unset.
+      will be transparent. The color can be an ``RGB`` color, a string
+      (for :doc:`color_list`), or a mapped color integer. If ``None`` is passed,
+      the colorkey will be unset.
 
       The colorkey will be ignored if the Surface is formatted to use per pixel
       alpha values. The colorkey can be mixed with the full Surface alpha
@@ -461,10 +462,10 @@
       | :sl:`set the color value for a single pixel`
       | :sg:`set_at((x, y), Color) -> None`
 
-      Set the ``RGBA`` or mapped integer color value for a single pixel. If the
-      Surface does not have per pixel alphas, the alpha value is ignored.
-      Setting pixels outside the Surface area or outside the Surface clipping
-      will have no effect.
+      Set the color of a single pixel at the specified coordinates to be an ``RGB``,
+      ``RGBA``, string (for :doc:`color_list`), or mapped integer color value. If the Surface
+      does not have per pixel alphas, the alpha value is ignored. Setting pixels outside the
+      Surface area or outside the Surface clipping will have no effect.
 
       Getting and setting pixels one at a time is generally too slow to be used
       in a game or realtime situation.
@@ -534,7 +535,7 @@
       Set the full palette for an 8-bit Surface. This will replace the colors in
       the existing palette. A partial palette can be passed and only the first
       colors in the original palette will be changed.
-
+      
       This function has no effect on a Surface with more than 8-bits per pixel.
 
       .. ## Surface.set_palette ##
@@ -546,7 +547,7 @@
 
       Set the palette value for a single entry in a Surface palette. The index
       should be a value from 0 to 255.
-
+      
       This function has no effect on a Surface with more than 8-bits per pixel.
 
       .. ## Surface.set_palette_at ##

src_c/doc/surface_doc.h

@@ -8,7 +8,7 @@
 #define DOC_SURFACE_COPY "copy() -> Surface\ncreate a new copy of a Surface"
 #define DOC_SURFACE_FILL "fill(color, rect=None, special_flags=0) -> Rect\nfill Surface with a solid color"
 #define DOC_SURFACE_SCROLL "scroll(dx=0, dy=0) -> None\nShift the surface image in place"
-#define DOC_SURFACE_SETCOLORKEY "set_colorkey(Color, flags=0) -> None\nset_colorkey(None) -> None\nSet the transparent colorkey"
+#define DOC_SURFACE_SETCOLORKEY "set_colorkey(color, flags=0) -> None\nset_colorkey(None) -> None\nSet the transparent colorkey"
 #define DOC_SURFACE_GETCOLORKEY "get_colorkey() -> RGB or None\nGet the current transparent colorkey"
 #define DOC_SURFACE_SETALPHA "set_alpha(value, flags=0) -> None\nset_alpha(None) -> None\nset the alpha value for the full Surface image"
 #define DOC_SURFACE_GETALPHA "get_alpha() -> int_value\nget the current Surface transparency value"