From 6673d035d03dfb574bef81ab05a97e137af4685d Mon Sep 17 00:00:00 2001
From: patnr <patrick.n.raanes@gmail.com>
Date: Thu, 9 Jun 2022 16:32:31 +0200
Subject: [PATCH] Re-order documentation a little

---
 dapper/xp_process.py | 38 +++++++++++++++++++++-----------------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/dapper/xp_process.py b/dapper/xp_process.py
index e4f86a3d..c2f7643a 100644
--- a/dapper/xp_process.py
+++ b/dapper/xp_process.py
@@ -43,23 +43,19 @@ class SparseSpace(dict):
     This is essentially a "groupby" operation, and indeed the case could
     be made that this class should be replaced by `pandas.DataFrame`.
 
+    The convenience method `.subspace` (aliased to `.__call__`),
+    which makes use of `.coords_matching`,
+    can be used to select items by their attribute values.
     In addition, `__getitem__` is quite flexible, allowing accessing by:
 
-    - The actual key, a `self.Coord` object, or a standard tuple. Returns single item.
-    - A `slice` or `list`. Returns list.
-      Can be used to get single item with `dct[[idx]][0]`.
-
-    Of course, indexing by slice or list assumes that the dict is ordered,
-    which we inherit from the builtin `dict` since Python 3.7.
-    Moreover, it is a reflection of the fact that the internals of this class
-    work by looping over items.
-
-    Other convenience functions: `.subspace` (alias `.__call__`) and `.coords_matching`.
-
-    Inspired by
-
-    - https://stackoverflow.com/a/7728830
-    - https://stackoverflow.com/q/3387691
+    - The actual key, a `self.Coord` object, or a standard tuple.<br>
+      Returns single item.
+    - A `slice` or `list`.<br>
+      Returns list.<br>
+      *PS: indexing by slice or list assumes that the dict is ordered,
+      which we inherit from the builtin `dict` since Python 3.7.
+      Moreover, it is a reflection of the fact that the internals of this class
+      work by looping over items.*
 
     Example:
     >>> dct = xpSpace(["x", "y", "z"])
@@ -67,14 +63,22 @@ class SparseSpace(dict):
     >>> dct[1, 2, 3] == dct[(1, 2, 3)] == dct[dct.Coord(1, 2, 3)] == "point 1"
     True
 
+    Notice the different ways to access *a single* `xp`.
+    Another way, combining `.subspace` and list accessing: e.g. `dct[[0]][0]`.
+    The reason why nothing less clunky is implemented for getting only 1 item
+    is that Coordinates can have any value. For example `None`:
+    >>> dct[(1, 2, None)] = "point 2"
+
     This dict only has three `dims`, so this fails:
     >>> dct[(1, 2, 3, 4)]
     Traceback (most recent call last):
     ...
     KeyError: (1, 2, 3, 4)
 
-    Individual coordinates can be anything. For example `None`:
-    >>> dct[(1, 2, None)] = "point 2"
+    Inspired by
+
+    - https://stackoverflow.com/a/7728830
+    - https://stackoverflow.com/q/3387691
     """
 
     @property