Accepted values for RECURRENCE_ID property looks strange

[stevepiercy]

When reviewing PR #1236, I found a weird docstring format.

https://icalendar--1236.org.readthedocs.build/en/1236/reference/api/icalendar.cal.event.html#icalendar.cal.event.Event.RECURRENCE_ID

Observe that the property has type hints that hyperlink, but the "Accepted values:" section heading is a wall of text. It's also not a standard section heading.

It's generated in this method.

icalendar/src/icalendar/attr.py

Lines 954 to 958 in bb480a9

	Accepted values: {", ".join(t.__name__ for t in value_type)}.
	If the attribute has invalid values, we raise InvalidCalendar.
	If the value is absent, we return None.
	You can also delete the value with del or by setting it to None.
	"""

With the following snippet, it appears somewhat better.

To delete the value, either use ``del`` or set it to ``None``.

Returns:
    If the value is absent, return ``None``.

Raises:
    :exc:`~icalendar.error.InvalidCalendar`
        If the attribute has invalid values.

I think that "Accepted values" is redundant to the type hints, so I'd remove it.

I'd keep the usage text, however, and append it to the description. This could be a problem, though, if there are other heading sections in the original docstring after the description.

@niccokunzmann what do you think?

[niccokunzmann]

That looks good. Could it also be a good example for #1244? Removing the extra type hints is good - I think they were there before we had good linking and typing. Thanks for tidying up!

[stevepiercy]

I checked git blame, and you had added it almost a year ago, before we knew how to Sphinx as well as we do now.

Yeah, let's make this issue a sub-issue. Done!

[mvanhorn]

Implemented in #1458 — removed the redundant Accepted values: line and reformatted the generated property docstrings into standard Sphinx Returns:/Raises: sections, matching the snippet approved here.