Restore PolarTransform(apply_theta_transforms) parameter

This partially reverts commit 6083ecd,
but with a full deprecation of the parameter as a whole.

Fixes matplotlib#31624

Author: QuLogic

doc/api/next_api_changes/deprecations/31630-ES.rst

@@ -0,0 +1,10 @@
+``apply_theta_transforms`` option in ``PolarTransform``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Applying theta transforms in `~matplotlib.projections.polar.PolarTransform` and
+`~matplotlib.projections.polar.InvertedPolarTransform` has been removed, and the
+*apply_theta_transforms* keyword argument is deprecated for both classes.
+
+If you need to retain the behaviour where theta values are transformed, chain the
+``PolarTransform`` with a `~matplotlib.transforms.Affine2D` transform that performs the
+theta shift and/or sign shift.

doc/api/next_api_changes/removals/30004-DS.rst

@@ -34,7 +34,9 @@ class PolarTransform(mtransforms.Transform):
 
     input_dims = output_dims = 2
 
-    def __init__(self, axis=None, use_rmin=True, *, scale_transform=None):
+    @_api.delete_parameter('3.11', 'apply_theta_transforms')
+    def __init__(self, axis=None, use_rmin=True, *,
+                 apply_theta_transforms=False, scale_transform=None):
         """
         Parameters
         ----------
@@ -183,7 +185,9 @@ class InvertedPolarTransform(mtransforms.Transform):
     """
     input_dims = output_dims = 2
 
-    def __init__(self, axis=None, use_rmin=True):
+    @_api.delete_parameter('3.11', 'apply_theta_transforms')
+    def __init__(self, axis=None, use_rmin=True,
+                 *, apply_theta_transforms=False):
         """
         Parameters
         ----------

lib/matplotlib/projections/polar.py

@@ -18,6 +18,7 @@ class PolarTransform(mtransforms.Transform):
         axis: PolarAxes | None = ...,
         use_rmin: bool = ...,
         *,
+        apply_theta_transforms: bool = ...,
         scale_transform: mtransforms.Transform | None = ...,
     ) -> None: ...
     def inverted(self) -> InvertedPolarTransform: ...
@@ -34,6 +35,8 @@ class InvertedPolarTransform(mtransforms.Transform):
         self,
         axis: PolarAxes | None = ...,
         use_rmin: bool = ...,
+        *,
+        apply_theta_transforms: bool = ...,
     ) -> None: ...
     def inverted(self) -> PolarTransform: ...