Skip to content

gh-138772: Improve documentation for turtle color functions #139325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+41 −11
Open

gh-138772: Improve documentation for turtle color functions #139325

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 41 additions & 11 deletions Doc/library/turtle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -777,13 +777,17 @@ Turtle motion
180.0


.. function:: dot(size=None, *color)
.. function:: dot()
dot(size)
dot(color, /)
dot(size, color, /)
dot(size, r, g, b, /)

:param size: an integer >= 1 (if given)
:param color: a colorstring or a numeric color tuple

Draw a circular dot with diameter *size*, using *color*. If *size* is
not given, the maximum of pensize+4 and 2*pensize is used.
not given, the maximum of ``pensize+4`` and ``2*pensize`` is used.


.. doctest::
Expand Down Expand Up @@ -1152,7 +1156,9 @@ Drawing state
Color control
~~~~~~~~~~~~~

.. function:: pencolor(*args)
.. function:: pencolor()
pencolor(color, /)
pencolor(r, g, b, /)

Return or set the pencolor.

Expand All @@ -1161,7 +1167,7 @@ Color control
``pencolor()``
Return the current pencolor as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor call.
color/pencolor/fillcolor/bgcolor call.

``pencolor(colorstring)``
Set pencolor to *colorstring*, which is a Tk color specification string,
Expand Down Expand Up @@ -1201,7 +1207,9 @@ Color control
(50.0, 193.0, 143.0)


.. function:: fillcolor(*args)
.. function:: fillcolor()
fillcolor(color, /)
fillcolor(r, g, b, /)

Return or set the fillcolor.

Expand All @@ -1210,7 +1218,7 @@ Color control
``fillcolor()``
Return the current fillcolor as color specification string, possibly
in tuple format (see example). May be used as input to another
color/pencolor/fillcolor call.
color/pencolor/fillcolor/bgcolor call.

``fillcolor(colorstring)``
Set fillcolor to *colorstring*, which is a Tk color specification string,
Expand Down Expand Up @@ -1244,7 +1252,10 @@ Color control
(255.0, 255.0, 255.0)


.. function:: color(*args)
.. function:: color()
color(color, /)
color(r, g, b, /)
color(pencolor, fillcolor, /)

Return or set pencolor and fillcolor.

Expand Down Expand Up @@ -1870,13 +1881,32 @@ Most of the examples in this section refer to a TurtleScreen instance called
Window control
--------------

.. function:: bgcolor(*args)
.. function:: bgcolor()
bgcolor(color, /)
bgcolor(r, g, b, /)

:param args: a color string or three numbers in the range 0..colormode or a
3-tuple of such numbers
Return or set the background color of the TurtleScreen.

Four input formats are allowed:

``bgcolor()``
Return the current background color as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor/bgcolor call.

``bgcolor(colorstring)``
Set the background color to *colorstring*, which is a Tk color
specification string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.

Set or return background color of the TurtleScreen.
``bgcolor((r, g, b))``
Set the background color to the RGB color represented by the tuple of
*r*, *g*, and *b*.
Each of *r*, *g*, and *b* must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see :func:`colormode`).

``bgcolor(r, g, b)``
Set the background color to the RGB color represented by *r*, *g*, and *b*. Each of
*r*, *g*, and *b* must be in the range 0..colormode.
Comment on lines +1890 to +1909
Copy link
Member

Choose a reason for hiding this comment

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

Do you think it could it be better to link to a more commonly used function, rather than repeat all the info?

Suggested change
Four input formats are allowed:
``bgcolor()``
Return the current background color as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor/bgcolor call.
``bgcolor(colorstring)``
Set the background color to *colorstring*, which is a Tk color
specification string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
Set or return background color of the TurtleScreen.
``bgcolor((r, g, b))``
Set the background color to the RGB color represented by the tuple of
*r*, *g*, and *b*.
Each of *r*, *g*, and *b* must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see :func:`colormode`).
``bgcolor(r, g, b)``
Set the background color to the RGB color represented by *r*, *g*, and *b*. Each of
*r*, *g*, and *b* must be in the range 0..colormode.
The arguments use the same format as :func:`fillcolor`.


.. doctest::
:skipif: _tkinter is None
Expand Down
Loading