[docs] Fix Deprecated annotation indentation (#31532)

Our Documentation build job currently returns errors like this:

/ray/python/ray/air/checkpoint.py:docstring of ray.air.checkpoint.Checkpoint.from_object_ref:9: WARNING: Content block expected for the "warning" directive; none found.
The reason for this is the Deprecated annotation that adds a warning block to the __doc__ property to be rendered in our documentation.

The code is faulty: A misplaced newline character in the DEPRECATED message block removes the proper indentation:

        Returns:
            If called by a driver, this returns the job ID. If called in
            a task, return the job ID of the associated driver.

        .. warning::
            
    DEPRECATED: This API is deprecated and may be removed in future Ray releases.
Use get_job_id() instead
Additionally, newline characters in the deprecation message are also not indented correctly:

        Returns:
            If called by a driver, this returns the job ID. If called in
            a task, return the job ID of the associated driver.

        .. warning::

            DEPRECATED: This API is deprecated and may be removed in future Ray releases.
Use get_job_id() instead
This PR fixes both problems:

        Returns:
            If called by a driver, this returns the job ID. If called in
            a task, return the job ID of the associated driver.

        .. warning::

            DEPRECATED: This API is deprecated and may be removed in future Ray releases.
            Use get_job_id() instead
        
Signed-off-by: Kai Fricke <[email protected]>

Author: krfricke

python/ray/util/annotations.py

@@ -124,7 +124,7 @@ def Deprecated(*args, **kwargs):
         return Deprecated()(args[0])
 
     doc_message = (
-        "\n    DEPRECATED: This API is deprecated and may be removed "
+        "**DEPRECATED**: This API is deprecated and may be removed "
         "in future Ray releases."
     )
     warning_message = (
@@ -179,10 +179,14 @@ def _append_doc(obj, *, message: str, directive: Optional[str] = None) -> str:
 
     indent = _get_indent(obj.__doc__)
     obj.__doc__ += "\n\n"
+
     if directive is not None:
-        obj.__doc__ += f"{' ' * indent}.. {directive}::\n"
+        obj.__doc__ += f"{' ' * indent}.. {directive}::\n\n"
+
+        message = message.replace("\n", "\n" + " " * (indent + 4))
         obj.__doc__ += f"{' ' * (indent + 4)}{message}"
     else:
+        message = message.replace("\n", "\n" + " " * (indent + 4))
         obj.__doc__ += f"{' ' * indent}{message}"
     obj.__doc__ += f"\n{' ' * indent}"