From 50de04ac92af1dea1a9e4ff078c05c1ff6737272 Mon Sep 17 00:00:00 2001
From: xqt <info@gno.de>
Date: Sun, 1 Dec 2024 18:46:42 +0100
Subject: [PATCH] doc: Enable docstring with classproperty methods

- modify docstring of classproperty methods to show a preleading
  classproperty and add rtype if present.
- return the modified decorator class when Sphinx is running.

Bug: T380628
Change-Id: Ie44c9f89d34e7cf4aec332daf8cbed9b30ac0dc8
---
 pywikibot/tools/__init__.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/pywikibot/tools/__init__.py b/pywikibot/tools/__init__.py
index 298f0950c6..7375d0de65 100644
--- a/pywikibot/tools/__init__.py
+++ b/pywikibot/tools/__init__.py
@@ -177,12 +177,20 @@ def bar(cls):  # a class property method
     """
 
     def __init__(self, cls_method) -> None:
-        """Hold the class method."""
+        """Initializer: hold the class method and documentation."""
         self.method = cls_method
-        self.__doc__ = self.method.__doc__
+        self.__annotations__ = self.method.__annotations__
+        self.__doc__ = (':class:`classproperty<tools.classproperty>` '
+                        f'{self.method.__doc__}')
+        rtype = self.__annotations__.get('return')
+        if rtype:
+            self.__doc__ += f'\n\n:rtype: {rtype}'
 
     def __get__(self, instance, owner):
         """Get the attribute of the owner class by its method."""
+        if SPHINX_RUNNING:
+            return self
+
         return self.method(owner)