Ensures that @qfunc_transform decorated functions display their signatures in the docs

doc/releases/changelog-dev.md

@@ -405,6 +405,10 @@
   usage of the passed `substep_optimizer` and its keyword arguments.
   [(#2160)](https://github.com/PennyLaneAI/pennylane/pull/2160)
 
+* Ensures that signatures of `@qml.qfunc_transform` decorated functions
+  display correctly in the docs.
+  [(#2286)](https://github.com/PennyLaneAI/pennylane/pull/2286)
+
 <h3>Operator class refactor</h3>
 
 The Operator class has undergone a major refactor with the following changes:

pennylane/transforms/qfunc_transforms.py

@@ -16,6 +16,8 @@
 from copy import deepcopy
 import functools
 import inspect
+import os
+import warnings
 
 import pennylane as qml
 
@@ -374,6 +376,21 @@ def new_qfunc(*args, **kwargs):
         the queueing logic required under steps (1) and (3), so that it does not need to be
         repeated and tested for every new qfunc transform.
     """
+    if os.environ.get("SPHINX_BUILD") == "1":
+        # If called during a Sphinx documentation build,
+        # simply return the original function rather than
+        # instantiating the object. This allows the signature to
+        # be correctly displayed in the documentation.
+
+        warnings.warn(
+            "qfunc transformations have been disabled, as a Sphinx "
+            "build has been detected via SPHINX_BUILD='1'. If this is not the "
+            "case, please set the environment variable SPHINX_BUILD='0'.",
+            UserWarning,
+        )
+
+        return tape_transform
+
     if not callable(tape_transform):
         raise ValueError(
             "The qfunc_transform decorator can only be applied "

tests/transforms/test_qfunc_transform.py

@@ -302,6 +302,27 @@ def ansatz():
         assert np.allclose(normal_result, transformed_result)
         assert normal_result.shape == transformed_result.shape
 
+    def test_sphinx_build(self, monkeypatch):
+        """Test that qfunc transforms are not created during Sphinx builds"""
+
+        def original_fn(tape):
+            for op in tape.operations + tape.measurements:
+                if op.name == "Hadamard":
+                    qml.RZ(np.pi, wires=op.wires)
+                    qml.RY(np.pi / 2, wires=op.wires)
+                else:
+                    op.queue()
+
+        decorated_transform = qml.qfunc_transform(original_fn)
+        assert original_fn is not decorated_transform
+
+        monkeypatch.setenv("SPHINX_BUILD", "1")
+
+        with pytest.warns(UserWarning, match="qfunc transformations have been disabled"):
+            decorated_transform = qml.qfunc_transform(original_fn)
+
+        assert original_fn is decorated_transform
+
 
 ############################################
 # Test transform, ansatz, and qfunc function