docs: Fix _dispatch.py

Author: dangotbanned

docs/api-reference-plan/ir/misc.md

@@ -47,10 +47,6 @@ somewhere less private
       members:
         - FunctionFlags
 
-<!-- 
-TODO @dangotbanned: Fix formatting
-TODO @dangotbanned: Docs contain an idea for rewriting them ffs
--->
 
 ::: narwhals._plan._dispatch
     options:

src/narwhals/_plan/_dispatch.py

@@ -105,25 +105,29 @@ def name(self) -> str:
         """Compliant-level method name.
 
         They're often the lowercase transform of the class name:
-        >>> import narwhals as nw
-        >>> import narwhals._plan as nwp
-        >>> from narwhals._plan import expressions as ir
-        >>> expr = nwp.col("a").cast(nw.Int64())._ir
-        >>> type(expr).__name__, get_dispatch_name(expr)
-        ('Cast', 'cast')
+
+            >>> import narwhals as nw
+            >>> import narwhals._plan as nwp
+            >>> from narwhals._plan import expressions as ir
+            >>> expr = nwp.col("a").cast(nw.Int64())._ir
+            >>> type(expr).__name__, get_dispatch_name(expr)
+            ('Cast', 'cast')
 
         *PascalCase* becomes *snake_case*:
-        >>> expr = nwp.col("a").over(order_by="b")._ir
-        >>> type(expr).__name__, get_dispatch_name(expr)
-        ('OverOrdered', 'over_ordered')
+
+            >>> expr = nwp.col("a").over(order_by="b")._ir
+            >>> type(expr).__name__, get_dispatch_name(expr)
+            ('OverOrdered', 'over_ordered')
 
         Accessor methods reflect the full dotted path:
-        >>> ir.lists.NUnique.__expr_ir_dispatch__.name
-        'list.n_unique'
+
+            >>> ir.lists.NUnique.__expr_ir_dispatch__.name
+            'list.n_unique'
 
         For functions, generated names can be overridden at class definition time:
-        >>> ir.boolean.Not.__expr_ir_dispatch__.name
-        'not_'
+
+            >>> ir.boolean.Not.__expr_ir_dispatch__.name
+            'not_'
         """
         return self._name
 
@@ -195,7 +199,8 @@ def options(self) -> DispatcherOptions:
         When a `Function` is subclassed, this property is inherited and reused in a new
         `FunctionDispatch` instance.
 
-        See `DispatcherOptions` for examples.
+        See Also:
+            [`DispatcherOptions`][narwhals._plan._dispatch.DispatcherOptions]
         """
         return self._options
 
@@ -365,40 +370,43 @@ class DispatcherOptions:
     Defined via the (optional) `dispatch` parameter at [subclass-definition time].
 
     Many functions simply use the default:
-    >>> from narwhals._plan import expressions as ir
-    >>> from narwhals._plan._dispatch import DispatcherOptions
-    >>> from narwhals._plan.options import ExplodeOptions
-    >>>
-    >>> class Explode(ir.Function): ...
 
-    >>> Explode.__expr_ir_dispatch__
-    Dispatch<explode>
+        >>> from narwhals._plan import expressions as ir
+        >>> from narwhals._plan._dispatch import DispatcherOptions
+        >>> from narwhals._plan.options import ExplodeOptions
+        >>>
+        >>> class Explode(ir.Function): ...
+
+        >>> Explode.__expr_ir_dispatch__
+        Dispatch<explode>
 
-    >>> Explode.__expr_ir_dispatch__.options
-    DispatcherOptions(<default>)
+        >>> Explode.__expr_ir_dispatch__.options
+        DispatcherOptions(<default>)
 
     `dispatch` provides a bit more flexibility when you want it:
 
-    >>> class Explode2(Explode, dispatch=DispatcherOptions.renamed("explodier")): ...
+        >>> class Explode2(Explode, dispatch=DispatcherOptions.renamed("explodier")): ...
 
-    >>> Explode2.__expr_ir_dispatch__
-    Dispatch<explodier>
+        >>> Explode2.__expr_ir_dispatch__
+        Dispatch<explodier>
 
-    >>> Explode2.__expr_ir_dispatch__.options
-    DispatcherOptions(override_name='explodier')
+        >>> Explode2.__expr_ir_dispatch__.options
+        DispatcherOptions(override_name='explodier')
 
     Keep in mind that `options` are inherited:
-    >>> class Explode21(Explode2): ...
-    >>> Explode21.__expr_ir_dispatch__
-    Dispatch<explodier>
+
+        >>> class Explode21(Explode2): ...
+        >>> Explode21.__expr_ir_dispatch__
+        Dispatch<explodier>
 
     So we'd need another override to get the default back:
-    >>> class ExplodeWithOptions(Explode2, dispatch=DispatcherOptions()):
-    ...     __slots__ = ("options",)
-    ...     options: ExplodeOptions
 
-    >>> ExplodeWithOptions.__expr_ir_dispatch__
-    Dispatch<explode_with_options>
+        >>> class ExplodeWithOptions(Explode2, dispatch=DispatcherOptions()):
+        ...     __slots__ = ("options",)
+        ...     options: ExplodeOptions
+
+        >>> ExplodeWithOptions.__expr_ir_dispatch__
+        Dispatch<explode_with_options>
 
     [subclass-definition time]: https://docs.python.org/3/reference/datamodel.html#object.__init_subclass__
     """
@@ -474,12 +482,12 @@ def merge_with(self, child: DispatcherOptions | None) -> DispatcherOptions:
         If an `accessor_name` was defined, it is **sticky** and will be merged
         with options of `child`:
 
-        >>> from narwhals._plan._function import Function
-        >>> options = DispatcherOptions
-        >>> class StringFunction(Function, dispatch=options(accessor_name="str")): ...
-        >>> class ZFill(StringFunction, dispatch=options.renamed("zfill")): ...
-        >>> get_dispatch_name(ZFill)
-        'str.zfill'
+            >>> from narwhals._plan._function import Function
+            >>> options = DispatcherOptions
+            >>> class StringFunction(Function, dispatch=options(accessor_name="str")): ...
+            >>> class ZFill(StringFunction, dispatch=options.renamed("zfill")): ...
+            >>> get_dispatch_name(ZFill)
+            'str.zfill'
         """
         options = child or self
         if accessor_name := (self.accessor_name or options.accessor_name):