docs: update docstrings with deprecated directive

ops/charm.py

@@ -387,11 +387,12 @@ class LeaderElectedEvent(HookEvent):
 
 
 class LeaderSettingsChangedEvent(HookEvent):
-    """DEPRECATED. Event triggered when leader changes any settings.
+    """Event triggered when leader changes any settings.
 
-    This event has been deprecated in favor of using a Peer relation,
-    and having the leader set a value in the Application data bag for
-    that peer relation.  (see :class:`RelationChangedEvent`).
+    .. deprecated:: 2.4.0
+        This event has been deprecated in favor of using a Peer relation,
+        and having the leader set a value in the Application data bag for
+        that peer relation. (See :class:`RelationChangedEvent`.)
     """
 
 
@@ -1094,8 +1095,10 @@ class CharmEvents(ObjectEvents):
     """Triggered when a new leader has been elected (see :class:`LeaderElectedEvent`)."""
 
     leader_settings_changed = EventSource(LeaderSettingsChangedEvent)
-    """DEPRECATED. Triggered when leader changes any settings (see
+    """Triggered when leader changes any settings (see
     :class:`LeaderSettingsChangedEvent`).
+
+    .. deprecated: 2.4.0
     """
 
     collect_metrics = EventSource(CollectMetricsEvent)

ops/lib/__init__.py

@@ -14,9 +14,10 @@
 
 """Infrastructure for the opslib functionality.
 
-DEPRECATED: The ops.lib functionality is deprecated, and is superseded by
-charm libraries (https://juju.is/docs/sdk/library) and regular Python imports.
-We now prefer to do version selection at build (charmcraft pack) time.
+.. deprecated:: 2.1.0
+    The ops.lib functionality is deprecated, and is superseded by
+    charm libraries (https://juju.is/docs/sdk/library) and regular Python imports.
+    We now prefer to do version selection at build (charmcraft pack) time.
 """
 
 import logging
@@ -48,9 +49,6 @@
 def use(name: str, api: int, author: str) -> ModuleType:
     """Use a library from the ops libraries.
 
-    DEPRECATED: This function is deprecated. Prefer charm libraries instead
-    (https://juju.is/docs/sdk/library).
-
     Args:
         name: the name of the library requested.
         api: the API version of the library.
@@ -61,6 +59,10 @@ def use(name: str, api: int, author: str) -> ModuleType:
         ImportError: if the library cannot be found.
         TypeError: if the name, api, or author are the wrong type.
         ValueError: if the name, api, or author are invalid.
+
+    .. deprecated:: 2.1.0
+        This function is deprecated. Prefer charm libraries instead
+        (https://juju.is/docs/sdk/library).
     """
     warnings.warn("ops.lib is deprecated, prefer charm libraries instead",
                   category=DeprecationWarning)
@@ -101,8 +103,9 @@ def autoimport():
     otherwise changed in the current run, and the changes need to be seen.
     Otherwise libraries are found on first call of `use`.
 
-    DEPRECATED: This function is deprecated. Prefer charm libraries instead
-    (https://juju.is/docs/sdk/library).
+    .. deprecated:: 2.1.0
+        This function is deprecated. Prefer charm libraries instead
+        (https://juju.is/docs/sdk/library).
     """
     warnings.warn("ops.lib is deprecated, prefer charm libraries instead",
                   category=DeprecationWarning)

ops/model.py

@@ -177,10 +177,11 @@ def storages(self) -> 'StorageMapping':
     def pod(self) -> 'Pod':
         """Represents the definition of a pod spec in legacy Kubernetes models.
 
-        DEPRECATED: New charms should use the sidecar pattern with Pebble.
-
         Use :meth:`Pod.set_spec` to set the container specification for legacy
         Kubernetes charms.
+
+        .. deprecated:: 2.4.0
+            New charms should use the sidecar pattern with Pebble.
         """
         return self._pod
 
@@ -1904,10 +1905,12 @@ def fetch(self, name: str) -> Path:
 class Pod:
     """Represents the definition of a pod spec in legacy Kubernetes models.
 
-    DEPRECATED: New charms should use the sidecar pattern with Pebble.
-
     Currently only supports simple access to setting the Juju pod spec via
     :attr:`.set_spec`.
+
+    .. deprecated:: 2.4.0
+
+        New charms should use the sidecar pattern with Pebble.
     """
 
     def __init__(self, backend: '_ModelBackend'):
@@ -1998,7 +2001,7 @@ def index(self) -> int:
 
     @property
     def id(self) -> int:
-        """DEPRECATED. Use :attr:`Storage.index` instead."""
+        """.. deprecated:: 2.4.0 Use :attr:`Storage.index` instead."""
         logger.warning("model.Storage.id is being replaced - please use model.Storage.index")
         return self.index