Docstring url property 1244 (#1425)

* Fix: Add Examples section heading and increase indentation

- Rename news file to 1244.documentation.1 to avoid conflict
- Add 'Examples:' section heading
- Increase indentation of example code blocks (4 spaces)
- Ensure proper rendering in documentation

* fix: remove undefined source_property from __all__ exports

AI Disclosure:
- Model used: Gemini
- Interaction: Assisted in locating and resolving the F822 undefined name error in the __all__ list.

* Update src/icalendar/attr.py

Co-authored-by: Steve Piercy <web@stevepiercy.com>

---------

Co-authored-by: IoannaGiag <t8230022@aueb.gr>
Co-authored-by: Steve Piercy <web@stevepiercy.com>

Author: 3 people

news/1244.documentation.1

@@ -0,0 +1 @@
+Improved the documentation for ``attr.url_property`` by converting raw RFC text into a comprehensive Python docstring with usage examples and explicit RFC cross-references. Assisting tool: Gemini 1.5. @samrodri911

src/icalendar/attr.py

@@ -1353,28 +1353,65 @@ def fset(self: Component, value: str | StrEnum | None) -> None:
 
 url_property = single_string_property(
     "URL",
-    """A Uniform Resource Locator (URL) associated with the iCalendar object.
+    """A Uniform Resource Locator (URL) associated with a calendar component.
 
-Description:
-    This property may be used in a calendar component to
-    convey a location where a more dynamic rendition of the calendar
-    information associated with the calendar component can be found.
-    This memo does not attempt to standardize the form of the URI, nor
-    the format of the resource pointed to by the property value.  If
-    the URL property and Content-Location MIME header are both
-    specified, they MUST point to the same resource.
+This property specifies a URI where a more dynamic rendition of the calendar
+information can be found. It is commonly used to reference related resources
+or provide additional information about the component.
 
-Conformance:
-    This property can be specified once in the "VEVENT",
-    "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components.
-    Since :rfc:`7986`, this property can also be defined on a "VCALENDAR".
+According to :rfc:`5545#section-3.8.4.6`, this property can be specified
+once in "VEVENT", "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components.
+Since :rfc:`7986#section-5.5`, this property can also be defined on a
+"VCALENDAR". :rfc:`7953#section-3.1` allows this property in "VAVAILABILITY" components.
 
-Example:
-    The following is an example of this property:
+This property may be used in a calendar component to convey a location
+where a more dynamic rendition of the calendar information can be found.
+If both the URL property and Content-Location MIME header are specified,
+they MUST point to the same resource.
 
-    .. code-block:: ics
+This differs from the SOURCE property, which identifies where calendar
+data can be refreshed from, whereas URL provides an alternative
+representation of the current calendar data.
+
+Examples:
 
+    Set a URL for an event that references additional information:
+
+    .. code-block:: pycon
+
+        >>> from icalendar import Event
+        >>> event = Event()
+        >>> event.add('url', 'http://example.com/events/meeting-2025')
+        >>> print(event.to_ical().decode('utf-8'))
+        BEGIN:VEVENT
+        URL:http://example.com/events/meeting-2025
+        END:VEVENT
+
+    Set a URL for a calendar:
+
+    .. code-block:: pycon
+
+        >>> from icalendar import Calendar
+        >>> calendar = Calendar()
+        >>> calendar.add('url', 'http://example.com/pub/calendars/jsmith/mytime.ics')
+        >>> print(calendar.to_ical().decode('utf-8'))
+        BEGIN:VCALENDAR
         URL:http://example.com/pub/calendars/jsmith/mytime.ics
+        END:VCALENDAR
+
+See also:
+    :attr:`~icalendar.cal.calendar.Calendar.source` for specifying from where
+    calendar data can be refreshed.
+
+    icalendar implementations:
+
+    -   :attr:`Availability.url <icalendar.cal.availability.Availability.url>`
+    -   :attr:`Calendar.url <icalendar.cal.calendar.Calendar.url>`
+    -   :attr:`Event.url <icalendar.cal.event.Event.url>`
+    -   :attr:`FreeBusy.url <icalendar.cal.free_busy.FreeBusy.url>`
+    -   :attr:`Journal.url <icalendar.cal.journal.Journal.url>`
+    -   :attr:`Todo.url <icalendar.cal.todo.Todo.url>`
+
 
 """,
 )