update docs/newsfragments/docstrings

Author: jakkdl

docs/source/conf.py

@@ -229,6 +229,7 @@ def setup(app: Sphinx) -> None:
     "pyopenssl": ("https://www.pyopenssl.org/en/stable/", None),
     "sniffio": ("https://sniffio.readthedocs.io/en/latest/", None),
     "trio-util": ("https://trio-util.readthedocs.io/en/latest/", None),
+    "flake8-async": ("https://flake8-async.readthedocs.io/en/latest/", None),
 }
 
 # See https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html

docs/source/reference-core.rst

@@ -527,8 +527,12 @@ objects.
 
    .. autoattribute:: deadline
 
+   .. autoattribute:: relative_deadline
+
    .. autoattribute:: shield
 
+   .. automethod:: is_relative()
+
    .. automethod:: cancel()
 
    .. attribute:: cancelled_caught

newsfragments/2512.breaking.rst

@@ -0,0 +1,2 @@
+:func:`trio.move_on_after` and :func:`trio.fail_after` previously set the deadline relative to initialization time, instead of more intuitively upon entering the context manager. This might change timeouts if a program relied on this behavior. If you want to restore previous behavior you should instead use ``trio.move_on_at(trio.current_time() + ...)``.
+flake8-async has a new rule to catch this, in case you're supporting older trio versions. See :ref:`ASYNC121` (TODO: except it will be ASYNC122, I'm just making sure intersphinx work)

newsfragments/2512.deprecated.rst

@@ -1 +1 @@
-:func:`trio.move_on_after` and :func:`trio.fail_after` now allows setting the deadline to be relative to entering the context manager. This will be the default in the future, and to opt into the new behaviour you can pass ``timeout_from_enter=True``.  This does not matter in the vast majority of cases where initialization and entering of the context manager is in the same place, and those cases will not raise any :class:`DeprecationWarning`. For more information see :ref:`saved_relative_timeouts`.
+:meth:`CancelScope.relative_deadline` and :meth:`CancelScope.is_relative` added, as well as a ``relative_deadline`` parameter to ``__init__``. This allows initializing scopes ahead of time, but where the specified relative deadline doesn't count down until the scope is entered.

newsfragments/2512.feature.rst

@@ -44,7 +44,7 @@ def move_on_after(
           of the newly created cancel scope.
 
     Raises:
-      ValueError: if `seconds` is less than zero or NaN.
+      ValueError: if ``seconds`` is less than zero or NaN.
 
     """
     # duplicate validation logic to have the correct parameter name