[3.12] gh-108202: Document calendar.TextCalendar formatting helpers (GH-127608) ...

Document the following TextCalendar methods:
- formatday()
- formatmonthname()
- formatweekday()
- formatweekheader()

(cherry picked from commit bb73426cafb78691b249ffa50f1872ab6f899d4a)

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/library/calendar.rst b/Doc/library/calendar.rst
index 4b82e52bf3d8ba9a2111ccfaefd60e11cf7a86ee..9743e24ad2cdf0b72779a665044e96ad7ce3ede8 100644 (file)
--- a/Doc/library/calendar.rst
+++ b/Doc/library/calendar.rst
@@ -138,6 +138,14 @@ interpreted as prescribed by the ISO 8601 standard.  Year 0 is 1 BC, year -1 is
 
    :class:`TextCalendar` instances have the following methods:
 
+
+   .. method:: formatday(theday, weekday, width)
+
+      Return a string representing a single day formatted with the given *width*.
+      If *theday* is ``0``, return a string of spaces of
+      the specified width, representing an empty day. The *weekday* parameter
+      is unused.
+
    .. method:: formatweek(theweek, w=0)
 
       Return a single week in a string with no newline. If *w* is provided, it
@@ -145,6 +153,17 @@ 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.
 
+   .. 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)
 
@@ -154,6 +173,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.
 
+   .. method:: formatmonthname(theyear, themonth, width=0, withyear=True)
+
+      Return a string representing the month's name centered within the
+      specified *width*. If *withyear* is ``True``, include the year in the
+      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)
 
@@ -445,7 +470,7 @@ The :mod:`calendar` module exports the following data attributes:
 
    A sequence that represents the months of the year in the current locale.  This
    follows normal convention of January being month number 1, so it has a length of
-   13 and  ``month_name[0]`` is the empty string.
+   13 and ``month_name[0]`` is the empty string.
 
        >>> import calendar
        >>> list(calendar.month_name)