docs(CHANGES,MIGRATION): Note split window updates

Author: tony

CHANGES

@@ -15,6 +15,39 @@ $ pip install --user --upgrade --pre libtmux
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version above -->
 
+### Breaking changes
+
+#### Improved new sessions (#532)
+
+- `Session.new_window()` to {meth}`Session.new_window()`
+
+  - Learned `direction`, via {class}`~libtmux.constants.WindowDirection`).
+
+#### Improved window splitting (#532)
+
+- `Window.split_window()` to {meth}`Window.split()`
+
+  - Deprecate `Window.split_window()`
+
+- `Pane.split_window()` to {meth}`Pane.split()`
+
+  - Deprecate `Pane.split_window()`
+  - Learned `direction`, via {class}`~libtmux.constants.PaneDirection`).
+
+    - Deprecate `vertical` and `horizontal` in favor of `direction`.
+
+  - Learned `zoom`
+
+#### Tweak: Pane position (#532)
+
+It's now possible to retrieve the position of a pane in a window via a
+`bool` helper::
+
+- {attr}`Pane.at_left`
+- {attr}`Pane.at_right`
+- {attr}`Pane.at_bottom`
+- {attr}`Pane.at_right`
+
 ### Development
 
 - poetry: 1.7.1 -> 1.8.1

MIGRATION

@@ -25,6 +25,13 @@ _Detailed migration steps for the next version will be posted here._
 
 <!-- To the maintainers and contributors: please add migration details for the upcoming release here -->
 
+## 0.33.0: Deprecations for splitting (2024-03-03)
+
+### Deprecations (#532)
+
+- `Window.split_window()` to {meth}`Window.split()`
+- `Pane.split_window()` to {meth}`Pane.split()`
+
 ## 0.31.0: Renaming and command cleanup (2024-02-17)
 
 ### Cleanups (#527)

src/libtmux/pane.py

@@ -527,59 +527,56 @@ def split(
 
         Examples
         --------
-        >>> pane
-        Pane(%1 Window(@1 1:..., Session($1 ...)))
+        >>> (pane.at_left, pane.at_right,
+        ...  pane.at_top, pane.at_bottom)
+        (True, True,
+        True, True)
 
         >>> new_pane = pane.split()
 
-        >>> new_pane
-        Pane(%2 Window(@1 1:..., Session($1 ...)))
-
-        >>> new_pane.at_right
-        True
-
-        >>> new_pane.at_left
-        True
-
-        >>> new_pane.at_top
-        False
-
-        >>> new_pane.at_bottom
-        True
+        >>> (new_pane.at_left, new_pane.at_right,
+        ...  new_pane.at_top, new_pane.at_bottom)
+        (True, True,
+        False, True)
 
         >>> right_pane = pane.split(direction=PaneDirection.Right)
 
-        >>> right_pane
-        Pane(%3 Window(@1 1:..., Session($1 ...)))
-
-        >>> right_pane.at_right
-        True
+        >>> (right_pane.at_left, right_pane.at_right,
+        ...  right_pane.at_top, right_pane.at_bottom)
+        (False, True,
+        True, False)
 
-        >>> right_pane.at_left
-        False
+        >>> left_pane = pane.split(direction=PaneDirection.Left)
 
-        >>> right_pane.at_top
-        True
+        >>> (left_pane.at_left, left_pane.at_right,
+        ...  left_pane.at_top, left_pane.at_bottom)
+        (True, False,
+        True, False)
 
-        >>> right_pane.at_bottom
-        False
+        >>> top_pane = pane.split(direction=PaneDirection.Above)
 
-        >>> left_pane = pane.split(direction=PaneDirection.Left)
+        >>> (top_pane.at_left, top_pane.at_right,
+        ...  top_pane.at_top, top_pane.at_bottom)
+        (False, False,
+        True, False)
 
-        >>> left_pane
-        Pane(%4 Window(@1 1:..., Session($1 ...)))
+        >>> pane = session.new_window().active_pane
 
-        >>> left_pane.at_right
-        False
+        >>> top_pane = pane.split(direction=PaneDirection.Above, full_window_split=True)
 
-        >>> left_pane.at_left
-        True
+        >>> (top_pane.at_left, top_pane.at_right,
+        ...  top_pane.at_top, top_pane.at_bottom)
+        (True, True,
+        True, False)
 
-        >>> left_pane.at_top
-        True
+        >>> bottom_pane = pane.split(
+        ... direction=PaneDirection.Below,
+        ... full_window_split=True)
 
-        >>> left_pane.at_bottom
-        False
+        >>> (bottom_pane.at_left, bottom_pane.at_right,
+        ...  bottom_pane.at_top, bottom_pane.at_bottom)
+        (True, True,
+        False, True)
         """
         tmux_formats = ["#{pane_id}" + FORMAT_SEPARATOR]