gh-128317: Highlight today in colour in calendar CLI output (#128318)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

1 files changed, 27 insertions, 4 deletions

diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index 97ca34b..ace8529 100644
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -146,26 +146,34 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       the specified width, representing an empty day. The *weekday* parameter
       is unused.
 
-   .. method:: formatweek(theweek, w=0)
+   .. method:: formatweek(theweek, w=0, highlight_day=None)
 
       Return a single week in a string with no newline. If *w* is provided, it
       specifies the width of the date columns, which are centered. Depends
       on the first weekday as specified in the constructor or set by the
       :meth:`setfirstweekday` method.
 
+      .. versionchanged:: next
+         If *highlight_day* is given, this date is highlighted in color.
+         This can be :ref:`controlled using environment variables
+         <using-on-controlling-color>`.
+
+
    .. method:: formatweekday(weekday, width)
 
       Return a string representing the name of a single weekday formatted to
       the specified *width*. The *weekday* parameter is an integer representing
       the day of the week, where ``0`` is Monday and ``6`` is Sunday.
 
+
    .. method:: formatweekheader(width)
 
       Return a string containing the header row of weekday names, formatted
       with the given *width* for each column. The names depend on the locale
       settings and are padded to the specified width.
 
-   .. method:: formatmonth(theyear, themonth, w=0, l=0)
+
+   .. method:: formatmonth(theyear, themonth, w=0, l=0, highlight_day=None)
 
       Return a month's calendar in a multi-line string. If *w* is provided, it
       specifies the width of the date columns, which are centered. If *l* is
@@ -173,6 +181,12 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       on the first weekday as specified in the constructor or set by the
       :meth:`setfirstweekday` method.
 
+      .. versionchanged:: next
+         If *highlight_day* is given, this date is highlighted in color.
+         This can be :ref:`controlled using environment variables
+         <using-on-controlling-color>`.
+
+
    .. method:: formatmonthname(theyear, themonth, width=0, withyear=True)
 
       Return a string representing the month's name centered within the
@@ -180,12 +194,13 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       output. The *theyear* and *themonth* parameters specify the year
       and month for the name to be formatted respectively.
 
+
    .. method:: prmonth(theyear, themonth, w=0, l=0)
 
       Print a month's calendar as returned by :meth:`formatmonth`.
 
 
-   .. method:: formatyear(theyear, w=2, l=1, c=6, m=3)
+   .. method:: formatyear(theyear, w=2, l=1, c=6, m=3, highlight_day=None)
 
       Return a *m*-column calendar for an entire year as a multi-line string.
       Optional parameters *w*, *l*, and *c* are for date column width, lines per
@@ -194,6 +209,11 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
       :meth:`setfirstweekday` method.  The earliest year for which a calendar
       can be generated is platform-dependent.
 
+      .. versionchanged:: next
+         If *highlight_day* is given, this date is highlighted in color.
+         This can be :ref:`controlled using environment variables
+         <using-on-controlling-color>`.
+
 
    .. method:: pryear(theyear, w=2, l=1, c=6, m=3)
 
@@ -549,7 +569,7 @@ The :mod:`calendar` module defines the following exceptions:
 
 .. _calendar-cli:
 
-Command-Line Usage
+Command-line usage
 ------------------
 
 .. versionadded:: 2.5
@@ -687,6 +707,9 @@ The following options are accepted:
    The number of months printed per row.
    Defaults to 3.
 
+.. versionchanged:: next
+   By default, today's date is highlighted in color and can be
+   :ref:`controlled using environment variables <using-on-controlling-color>`.
 
 *HTML-mode options:*