docs: fix broken cross-references in documentation

CHANGES.rst

@@ -10,6 +10,7 @@ Change log
 Minor changes
 ~~~~~~~~~~~~~
 
+- Fix broken cross-references in documentation by replacing ``:py:`` prefixed roles with standard Sphinx roles and qualifying ambiguous references. See `#1158 <https://github.com/collective/icalendar/issues/1158>`_
 - ...
 
 Breaking changes

src/icalendar/cal/calendar.py

@@ -101,7 +101,7 @@ def events(self) -> list[Event]:
 
         This is a shortcut to get all events.
         Modifications do not change the calendar.
-        Use :py:meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
+        Use :meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
 
         >>> from icalendar import Calendar
         >>> calendar = Calendar.example()
@@ -119,7 +119,7 @@ def todos(self) -> list[Todo]:
 
         This is a shortcut to get all todos.
         Modifications do not change the calendar.
-        Use :py:meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
+        Use :meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
         """
         return self.walk("VTODO")
 
@@ -129,7 +129,7 @@ def journals(self) -> list[Journal]:
 
         This is a shortcut to get all journals.
         Modifications do not change the calendar.
-        Use :py:meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
+        Use :meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
         """
         return self.walk("VJOURNAL")
 
@@ -139,7 +139,7 @@ def availabilities(self) -> list[Availability]:
 
         This is a shortcut to get all availabilities.
         Modifications do not change the calendar.
-        Use :py:meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
+        Use :meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
         """
         return self.walk("VAVAILABILITY")
 
@@ -149,7 +149,7 @@ def freebusy(self) -> list[FreeBusy]:
 
         This is a shortcut to get all FreeBusy.
         Modifications do not change the calendar.
-        Use :py:meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
+        Use :meth:`Component.add_component <icalendar.cal.component.Component.add_component>`.
         """
         return self.walk("VFREEBUSY")
 

src/icalendar/cal/lazy.py

@@ -188,7 +188,7 @@ class LazyCalendar(Calendar):
             >>> calendar.is_lazy()
             True
 
-        When you access all :attr:`subcomponents` of the calendar,
+        When you access all :attr:`~icalendar.cal.component.Component.subcomponents` of the calendar,
         for example by getting their count, the entire calendar is
         parsed and becomes not lazy.
 

src/icalendar/cal/todo.py

@@ -382,7 +382,7 @@ def new(
             url: The :attr:`url` of the todo.
 
         Returns:
-            :class:`Todo`
+            :class:`~icalendar.cal.todo.Todo`
 
         Raises:
             ~error.InvalidCalendar: If the content is not valid

src/icalendar/caselessdict.py

@@ -173,7 +173,8 @@ def get(self, key: Any, default: Any = None) -> Any:
     def setdefault(self, key: Any, value: Any = None) -> Any:
         """Create the (key, value) pair, optionally with a ``value``.
 
-        Once set, to change default value use :meth:`update`.
+        Once set, to change default value use
+        :meth:`~icalendar.caselessdict.CaselessDict.update`.
 
         Parameters:
             key: The key to look up or create, case-insensitively.
@@ -292,7 +293,8 @@ def __ne__(self, other: object) -> bool:
     def sorted_keys(self) -> list[str]:
         """Sort keys according to the canonical order for this class.
 
-        Keys listed in :attr:`canonical_order` appear first in that order.
+        Keys listed in :attr:`~icalendar.caselessdict.CaselessDict.canonical_order`
+        appear first in that order.
         Remaining keys appear alphabetically at the end.
 
         Returns:
@@ -303,7 +305,8 @@ def sorted_keys(self) -> list[str]:
     def sorted_items(self) -> list[tuple[Any, Any]]:
         """Sort items according to the canonical order for this class.
 
-        Items whose keys are listed in :attr:`canonical_order` appear first
+        Items whose keys are listed in
+        :attr:`~icalendar.caselessdict.CaselessDict.canonical_order` appear first
         in that order. Remaining items appear alphabetically by key.
 
         Returns:

src/icalendar/enums.py

@@ -118,7 +118,7 @@ class FBTYPE(StrEnum):
         ``BUSY_UNAVAILABLE``,
         ``BUSY_TENTATIVE``
 
-    See also :class:`BUSYTYPE`.
+    See also :class:`icalendar.enums.BUSYTYPE`.
 
     Purpose:
         To specify the free or busy time type.
@@ -416,7 +416,8 @@ class BUSYTYPE(StrEnum):
 
     Description:
         This property is used to specify the default busy time
-        type.  The values correspond to those used by the :class:`FBTYPE`
+        type.  The values correspond to those used by the
+        :class:`icalendar.enums.FBTYPE`
         parameter used on a "FREEBUSY" property, with the exception that
         the "FREE" value is not used in this property.  If not specified
         on a component that allows this property, the default is "BUSY-

src/icalendar/parser/ical/lazy.py

@@ -128,7 +128,8 @@ def parse(self) -> Component:
     def is_lazy(self) -> bool:
         """Return whether the subcomponents were accessed and parsed lazily.
 
-        Call :meth:`parse` to get the fully parsed component.
+        Call :meth:`~icalendar.parser.ical.lazy.LazySubcomponent.parse` to get the fully
+        parsed component.
         """
         return True
 

src/icalendar/parser/parameter.py

@@ -165,7 +165,8 @@ def q_split(st: str, sep: str = ",", maxsplit: int = -1) -> list[str]:
 def q_join(lst: Sequence[str], sep: str = ",", always_quote: bool = False) -> str:
     """Join a list with a separator, quoting items as needed.
 
-    Joins list items with the separator, applying :func:`dquote` to each item
+    Joins list items with the separator, applying
+    :func:`~icalendar.parser.parameter.dquote` to each item
     to add double quotes when they contain special characters.
 
     Parameters:

src/icalendar/parser/property.py

@@ -8,7 +8,8 @@
 def unescape_list_or_string(val: str | list[str]) -> str | list[str]:
     """Unescape a value that may be a string or list of strings.
 
-    Applies :func:`_unescape_string` to the value. If the value is a list,
+    Applies :func:`~icalendar.parser.string._unescape_string` to the value. If the value
+    is a list,
     unescapes each element.
 
     Parameters:
@@ -28,7 +29,7 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]:
 def unescape_backslash(val: str):
     r"""Unescape backslash sequences in iCalendar text.
 
-    Unlike :py:meth:`unescape_string`, this only handles actual backslash escapes
+    Unlike :meth:`unescape_string`, this only handles actual backslash escapes
     per :rfc:`5545`, not URL encoding. This preserves URL-encoded values
     like ``%3A`` in URLs.
 

src/icalendar/parser/string.py

@@ -47,7 +47,8 @@ def escape_char(text: str | bytes) -> str:
     r"""Format value according to iCalendar TEXT escaping rules.
 
     .. deprecated:: 7.0.0
-        Use the private :func:`_escape_char` internally. For external use,
+        Use the private :func:`~icalendar.parser.string._escape_char` internally. For
+        external use,
         this function is deprecated. Please use alternative escaping methods
         or contact the maintainers.
 
@@ -84,7 +85,8 @@ def escape_char(text: str | bytes) -> str:
 def _unescape_char(text: str | bytes) -> str | bytes | None:
     r"""Unescape iCalendar TEXT values.
 
-    Reverses the escaping applied by :func:`_escape_char` according to
+    Reverses the escaping applied by :func:`~icalendar.parser.string._escape_char`
+    according to
     :rfc:`5545#section-3.3.11` TEXT escaping rules.
 
     Parameters:
@@ -130,11 +132,13 @@ def unescape_char(text: str | bytes) -> str | bytes | None:
     r"""Unescape iCalendar TEXT values.
 
     .. deprecated:: 7.0.0
-        Use the private :func:`_unescape_char` internally. For external use,
+        Use the private :func:`~icalendar.parser.string._unescape_char` internally. For
+        external use,
         this function is deprecated. Please use alternative unescaping methods
         or contact the maintainers.
 
-    Reverses the escaping applied by :func:`escape_char` according to
+    Reverses the escaping applied by :func:`~icalendar.parser.string.escape_char`
+    according to
     :rfc:`5545#section-3.3.11` TEXT escaping rules.
 
     Parameters:
@@ -231,7 +235,8 @@ def escape_string(val: str) -> str:
     r"""Escape backslash sequences to URL-encoded hex values.
 
     .. deprecated:: 7.0.0
-        Use the private :func:`_escape_string` internally. For external use,
+        Use the private :func:`~icalendar.parser.string._escape_string` internally. For
+        external use,
         this function is deprecated.
     """
     warnings.warn(
@@ -246,7 +251,8 @@ def escape_string(val: str) -> str:
 def _unescape_string(val: str) -> str:
     r"""Unescape URL-encoded hex values to their original characters.
 
-    Reverses :func:`_escape_string` by converting percent-encoded hex values
+    Reverses :func:`~icalendar.parser.string._escape_string` by converting
+    percent-encoded hex values
     back to their original characters. This is used for parameter parsing.
 
     Parameters:
@@ -275,7 +281,8 @@ def unescape_string(val: str) -> str:
     r"""Unescape URL-encoded hex values to their original characters.
 
     .. deprecated:: 7.0.0
-        Use the private :func:`_unescape_string` internally. For external use,
+        Use the private :func:`~icalendar.parser.string._unescape_string` internally.
+        For external use,
         this function is deprecated.
     """
     warnings.warn(

src/icalendar/prop/dt/date.py

@@ -104,7 +104,7 @@ def to_jcal(self, name: str) -> list:
 
     @classmethod
     def parse_jcal_value(cls, jcal: str) -> date:
-        """Parse a jCal string to a :py:class:`datetime.date`.
+        """Parse a jCal string to a :class:`datetime.date`.
 
         Raises:
             ~error.JCalParsingError: If it can't parse a date.

src/icalendar/prop/dt/datetime.py

@@ -52,7 +52,7 @@ class vDatetime(TimeBase):
         vDatetime is timezone aware and uses a timezone library.
         When a vDatetime object is created from an
         ical string, you can pass a valid timezone identifier. When a
-        vDatetime object is created from a Python :py:mod:`datetime` object, it uses the
+        vDatetime object is created from a Python :mod:`datetime` object, it uses the
         tzinfo component, if present. Otherwise a timezone-naive object is
         created. Be aware that there are certain limitations with timezone naive
         DATE-TIME components in the icalendar standard.
@@ -155,7 +155,7 @@ def is_utc(self) -> bool:
 
     @classmethod
     def parse_jcal_value(cls, jcal: str) -> datetime:
-        """Parse a jCal string to a :py:class:`datetime.datetime`.
+        """Parse a jCal string to a :class:`datetime.datetime`.
 
         Raises:
             ~error.JCalParsingError: If it can't parse a date-time value.

src/icalendar/prop/dt/duration.py

@@ -166,7 +166,7 @@ def to_jcal(self, name: str) -> list:
 
     @classmethod
     def parse_jcal_value(cls, jcal: str) -> timedelta:
-        """Parse a jCal string to a :py:class:`datetime.timedelta`.
+        """Parse a jCal string to a :class:`datetime.timedelta`.
 
         Raises:
             ~error.JCalParsingError: If it can't parse a duration."""

src/icalendar/prop/dt/time.py

@@ -204,7 +204,7 @@ def to_jcal(self, name: str) -> list:
 
     @classmethod
     def parse_jcal_value(cls, jcal: str) -> time:
-        """Parse a jCal string to a :py:class:`datetime.time`.
+        """Parse a jCal string to a :class:`datetime.time`.
 
         Raises:
             ~error.JCalParsingError: If it can't parse a time.