jenkins-bot submitted this change.

View Change

[fix] show the right docstring with tools.deprecated

Previously the docstring of the outer wrapper of add_full_name
decorator was shown as the docstring of deprecated function.
Now remove the add_full_name when Sphinx is running.

Use the same technique with allow_asynchronous decorator.

Bug: T365286
Change-Id: I292bb7a3dc7a2804a77ce84dcf228848fc3239a4
---
M pywikibot/page/_decorators.py
M pywikibot/tools/_deprecate.py
2 files changed, 24 insertions(+), 21 deletions(-)

diff --git a/pywikibot/page/_decorators.py b/pywikibot/page/_decorators.py
index 9108cc8..38c2d1f 100644
--- a/pywikibot/page/_decorators.py
+++ b/pywikibot/page/_decorators.py
@@ -1,6 +1,6 @@
 """Decorators for Page objects."""
 #
-# (C) Pywikibot team, 2017-2022
+# (C) Pywikibot team, 2017-2024
 #
 # Distributed under the terms of the MIT license.
 #
@@ -12,20 +12,17 @@
     OtherPageSaveError,
     PageSaveRelatedError,
 )
-from pywikibot.tools import add_full_name, manage_wrapping
+from pywikibot.tools import SPHINX_RUNNING, add_full_name, manage_wrapping
 
 
-# decorating this function leads sphinx to hide it
-def _allow_asynchronous(func):
-    """
-    Decorator to make it possible to run a BasePage method asynchronously.
+def allow_asynchronous(func):
+    """Decorator to make it possible to run a BasePage method asynchronously.
 
-    This is done when the method is called with kwarg asynchronous=True.
-    Optionally, you can also provide kwarg callback, which, if provided, is
-    a callable that gets the page as the first and a possible exception that
-    occurred during saving in the second thread or None as the second argument.
-
-    :meta public:
+    This is done when the method is called with kwarg
+    :code:`asynchronous=True`. Optionally, you can also provide kwarg
+    callback, which, if provided, is a callable that gets the page as
+    the first and a possible exception that occurred during saving in
+    the second thread or None as the second argument.
     """
     def handle(func, self, *args, **kwargs):
         do_async = kwargs.pop('asynchronous', False)
@@ -59,5 +56,6 @@
     return wrapper
 
 
-#: `_allow_asynchronous` decorated with :func:`tools.add_full_name`
-allow_asynchronous = add_full_name(_allow_asynchronous)
+if not SPHINX_RUNNING:
+    # T365286: decorate allow_asynchronous function with add_full_name
+    allow_asynchronous = add_full_name(allow_asynchronous)
diff --git a/pywikibot/tools/_deprecate.py b/pywikibot/tools/_deprecate.py
index 58409ac..d8c56d3 100644
--- a/pywikibot/tools/_deprecate.py
+++ b/pywikibot/tools/_deprecate.py
@@ -36,6 +36,8 @@
 from typing import Any
 from warnings import warn
 
+from pywikibot.tools import SPHINX_RUNNING
+
 
 class _NotImplementedWarning(RuntimeWarning):
 
@@ -211,20 +213,18 @@
     warn(msg.format(name, instead), warning_class, depth + 1)
 
 
-@add_full_name
 def deprecated(*args, **kwargs):
     """Decorator to output a deprecation warning.
 
     .. versionchanged:: 7.0
        `since` keyword must be a release number, not a timestamp.
 
-    :keyword instead: if provided, will be used to specify the replacement
-    :type instead: str
-    :keyword since: a version string string when the method was deprecated
-    :type since: str
-    :keyword future_warning: if True a FutureWarning will be thrown,
+    :keyword str instead: if provided, will be used to specify the
+        replacement
+    :keyword str since: a version string string when the method was
+        deprecated
+    :keyword bool future_warning: if True a FutureWarning will be thrown,
         otherwise it provides a DeprecationWarning
-    :type future_warning: bool
     """
     def decorator(obj):
         """Outer wrapper.
@@ -304,6 +304,11 @@
     return decorator
 
 
+if not SPHINX_RUNNING:
+    # T365286: decorate deprecated function with add_full_name
+    deprecated = add_full_name(deprecated)
+
+
 def deprecate_arg(old_arg: str, new_arg: str | bool | None):
     """Decorator to declare old_arg deprecated and replace it with new_arg.
 

To view, visit change 1033192. To unsubscribe, or for help writing mail filters, visit settings.