diff --git a/docs/source/how-tos/grib/grib_array_namespace.ipynb b/docs/source/how-tos/grib/grib_array_namespace.ipynb
index 5bac248e..7175f35a 100644
--- a/docs/source/how-tos/grib/grib_array_namespace.ipynb
+++ b/docs/source/how-tos/grib/grib_array_namespace.ipynb
@@ -25,7 +25,7 @@
     "tags": []
    },
    "source": [
-    "In this example we will use a GRIB file containing 4 messages. First we ensure the file is available and read it into a fieldlist."
+    "In this example we will use a GRIB file containing 4 messages."
    ]
   },
   {
@@ -39,12 +39,26 @@
     },
     "tags": []
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "04d3229edb8841ecbc451a3f9a2eadae",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "test4.grib:   0%|          | 0.00/509k [00:00<?, ?B/s]"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
    "source": [
     "import earthkit.data as ekd\n",
     "\n",
-    "ekd.download_example_file(\"test4.grib\")\n",
-    "ds_in = ekd.from_source(\"file\", \"test4.grib\").to_fieldlist()"
+    "fl_in = ekd.from_source(\"sample\", \"test4.grib\").to_fieldlist()"
    ]
   },
   {
@@ -86,16 +100,6 @@
    "execution_count": 2,
    "id": "6ec4489f-2030-4a55-8292-7f50fb845677",
    "metadata": {},
-   "outputs": [],
-   "source": [
-    "ds = ds_in.to_fieldlist()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 3,
-   "id": "07e0823d-ff1d-43d1-8ffb-e5a6d0616ce4",
-   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -103,13 +107,14 @@
        "4"
       ]
      },
-     "execution_count": 3,
+     "execution_count": 2,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "len(ds)"
+    "fl = fl_in.to_fieldlist()\n",
+    "len(fl)"
    ]
   },
   {
@@ -130,7 +135,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 3,
    "id": "b3b30d9f-0edb-4938-baec-7026acd70192",
    "metadata": {
     "editable": true,
@@ -146,7 +151,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 4,
    "id": "5d2174d7-0f36-4b20-8ad5-bd93fd12f91b",
    "metadata": {
     "editable": true,
@@ -157,12 +162,12 @@
    },
    "outputs": [],
    "source": [
-    "ds = ds_in.to_fieldlist(array_namespace=\"torch\")"
+    "fl = fl_in.to_fieldlist(array_namespace=\"torch\")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 5,
    "id": "3c108a25-5f41-422f-9adb-98c932205dce",
    "metadata": {
     "editable": true,
@@ -266,13 +271,13 @@
        "3             850            pressure               0          regular_ll  "
       ]
      },
-     "execution_count": 6,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.ls()"
+    "fl.ls()"
    ]
   },
   {
@@ -306,7 +311,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 6,
    "id": "21a1e8b1-f0e5-4de6-bdbf-e92c5df5989e",
    "metadata": {
     "editable": true,
@@ -323,18 +328,18 @@
        "        228.0460, 228.0460, 228.0460], dtype=torch.float64)"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 6,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds[0].values[:10]"
+    "fl[0].values[:10]"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "id": "fbd92126-bb5b-47e5-80a7-d4bed3097764",
    "metadata": {
     "editable": true,
@@ -350,18 +355,18 @@
        "torch.Size([65160])"
       ]
      },
-     "execution_count": 8,
+     "execution_count": 7,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds[0].values.shape"
+    "fl[0].values.shape"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "id": "714b320c-90ea-4326-bc5f-340dda66daab",
    "metadata": {
     "editable": true,
@@ -377,13 +382,13 @@
        "torch.Size([4, 65160])"
       ]
      },
-     "execution_count": 9,
+     "execution_count": 8,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.values.shape"
+    "fl.values.shape"
    ]
   },
   {
@@ -417,7 +422,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 10,
+   "execution_count": 9,
    "id": "f60797eb-d578-4638-b1d0-bd18949dd249",
    "metadata": {
     "editable": true,
@@ -434,18 +439,18 @@
        "        [228.6085, 228.5792]], dtype=torch.float64)"
       ]
      },
-     "execution_count": 10,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds[0].to_array()[:2, :2]"
+    "fl[0].to_array()[:2, :2]"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "id": "f4d053fa-2acf-4949-9bbd-a0b2ccf30318",
    "metadata": {
     "editable": true,
@@ -461,18 +466,18 @@
        "torch.Size([4, 181, 360])"
       ]
      },
-     "execution_count": 11,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.to_array().shape"
+    "fl.to_array().shape"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 11,
    "id": "04cd31df-34cd-47a9-90cc-833b9805bd55",
    "metadata": {
     "editable": true,
@@ -488,13 +493,13 @@
        "torch.Size([4, 65160])"
       ]
      },
-     "execution_count": 12,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.to_array(flatten=True).shape"
+    "fl.to_array(flatten=True).shape"
    ]
   },
   {
@@ -528,7 +533,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 12,
    "id": "b60eea0f-0da1-48f1-a64e-f1b75e36a737",
    "metadata": {
     "editable": true,
@@ -545,18 +550,18 @@
        "       [228.60850525, 228.57920837]])"
       ]
      },
-     "execution_count": 13,
+     "execution_count": 12,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds[0].to_numpy()[:2, :2]"
+    "fl[0].to_numpy()[:2, :2]"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 13,
    "id": "ae6bd7cd-b043-4993-b715-e5ea2531490a",
    "metadata": {
     "editable": true,
@@ -572,40 +577,34 @@
        "(4, 181, 360)"
       ]
      },
-     "execution_count": 14,
+     "execution_count": 13,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.to_numpy().shape"
+    "fl.to_numpy().shape"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "920f6b98-f0e6-4ffc-a5e4-f8f643c23f76",
-   "metadata": {
-    "editable": true,
-    "slideshow": {
-     "slide_type": ""
-    },
-    "tags": []
-   },
+   "id": "48f6f5a4-1304-43ef-b357-563cfa071309",
+   "metadata": {},
    "source": [
-    "As expected, the values in *r1* are now differing by 2 from the ones in the original fieldlist (*r*)."
+    "### Building a fieldlist in a loop"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "48f6f5a4-1304-43ef-b357-563cfa071309",
+   "id": "7270c9ed-9bf9-4261-b949-b3f32d0af268",
    "metadata": {},
    "source": [
-    "### Building an array fieldlist in a loop"
+    "The following cell adds 2 to each field value and creates a new fieldlist from the modified fields."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 18,
    "id": "a4b086a5-406d-4d1c-bd93-1edbde84bf81",
    "metadata": {},
    "outputs": [
@@ -703,22 +702,36 @@
        "3             850            pressure               0          regular_ll  "
       ]
      },
-     "execution_count": 15,
+     "execution_count": 18,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "fields = []\n",
-    "for f in ds:\n",
+    "for f in fl:\n",
     "    fields.append(f.set(values=f.values + 2.0))\n",
     "r1 = ekd.create_fieldlist(fields)\n",
     "r1.ls()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "920f6b98-f0e6-4ffc-a5e4-f8f643c23f76",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "As expected, the values in *r1* are now differing by 2 from the ones in the original fieldlist (*r*)."
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 15,
    "id": "5b78ea8a-64e9-4bfa-9d11-8b390995994b",
    "metadata": {
     "editable": true,
@@ -735,7 +748,7 @@
        "        230.0460, 230.0460, 230.0460], dtype=torch.float64)"
       ]
      },
-     "execution_count": 16,
+     "execution_count": 15,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -776,7 +789,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 16,
    "id": "9ceea7b3-5059-4378-9a26-d282caa3b74a",
    "metadata": {
     "editable": true,
@@ -880,7 +893,7 @@
        "3             850            pressure               0          regular_ll  "
       ]
      },
-     "execution_count": 17,
+     "execution_count": 16,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -888,13 +901,13 @@
    "source": [
     "path = \"_from_pytroch.grib\"\n",
     "r1.to_target(\"file\", path)\n",
-    "ds1 = ekd.from_source(\"file\", path).to_fieldlist()\n",
-    "ds1.ls()"
+    "fl1 = ekd.from_source(\"file\", path).to_fieldlist()\n",
+    "fl1.ls()"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 18,
+   "execution_count": 17,
    "id": "1ed4315d-0078-4e2e-b8a1-88b132f71da0",
    "metadata": {},
    "outputs": [
@@ -906,14 +919,14 @@
        "       230.04600525, 230.04600525])"
       ]
      },
-     "execution_count": 18,
+     "execution_count": 17,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "# the modified values were correctly written to the GRIB file\n",
-    "ds1[0].values[:10]"
+    "fl1[0].values[:10]"
    ]
   },
   {
diff --git a/docs/source/how-tos/grib/grib_contents.ipynb b/docs/source/how-tos/grib/grib_contents.ipynb
index ed040886..b14b18c0 100644
--- a/docs/source/how-tos/grib/grib_contents.ipynb
+++ b/docs/source/how-tos/grib/grib_contents.ipynb
@@ -41,7 +41,7 @@
     {
      "data": {
       "application/vnd.jupyter.widget-view+json": {
-       "model_id": "f3160c346d904c93bacc5d7fbdba96ac",
+       "model_id": "234a1782252d42c885a0f608553d68b4",
        "version_major": 2,
        "version_minor": 0
       },
@@ -56,7 +56,7 @@
    "source": [
     "import earthkit.data as ekd\n",
     "\n",
-    "ds = ekd.from_source(\"sample\", \"test6.grib\").to_fieldlist()"
+    "fl = ekd.from_source(\"sample\", \"test6.grib\").to_fieldlist()"
    ]
   },
   {
@@ -69,7 +69,7 @@
     "tags": []
    },
    "source": [
-    "### Using ls(), head() and tail()"
+    "## ls()"
    ]
   },
   {
@@ -83,34 +83,7 @@
     "tags": []
    },
    "source": [
-    "All these methods (see e.g.: :py:meth:`~earthkit.data.core.fieldlist.FieldList.ls`) take the same set of keyword arguments."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "editable": true,
-    "slideshow": {
-     "slide_type": ""
-    },
-    "tags": []
-   },
-   "source": [
-    "#### ls()"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "editable": true,
-    "raw_mimetype": "text/restructuredtext",
-    "slideshow": {
-     "slide_type": ""
-    },
-    "tags": []
-   },
-   "source": [
-    ":py:meth:`~earthkit.data.core.fieldlist.FieldList.ls`)  lists all the fields:"
+    ":py:meth:`~earthkit.data.core.fieldlist.FieldList.ls`  lists all the fields:"
    ]
   },
   {
@@ -250,7 +223,7 @@
     }
    ],
    "source": [
-    "ds.ls()"
+    "fl.ls()"
    ]
   },
   {
@@ -264,6 +237,10 @@
    "cell_type": "code",
    "execution_count": 3,
    "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
     "tags": []
    },
    "outputs": [
@@ -341,13 +318,17 @@
     }
    ],
    "source": [
-    "ds.ls(2)"
+    "fl.ls(2)"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 4,
    "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
     "tags": []
    },
    "outputs": [
@@ -425,7 +406,7 @@
     }
    ],
    "source": [
-    "ds.ls(n=2)"
+    "fl.ls(n=2)"
    ]
   },
   {
@@ -445,7 +426,13 @@
   {
    "cell_type": "code",
    "execution_count": 5,
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -516,13 +503,19 @@
     }
    ],
    "source": [
-    "ds.ls(keys=\"time.base_datetime\")"
+    "fl.ls(keys=\"time.base_datetime\")"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 6,
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -600,7 +593,7 @@
     }
    ],
    "source": [
-    "ds.ls(keys=[\"time.base_datetime\", \"vertical.level\"])"
+    "fl.ls(keys=[\"time.base_datetime\", \"vertical.level\"])"
    ]
   },
   {
@@ -613,7 +606,13 @@
   {
    "cell_type": "code",
    "execution_count": 7,
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -708,6 +707,18 @@
        "      <td>regular_ll</td>\n",
        "      <td>meter / second</td>\n",
        "    </tr>\n",
+       "    <tr>\n",
+       "      <th>5</th>\n",
+       "      <td>v</td>\n",
+       "      <td>2018-08-01 12:00:00</td>\n",
+       "      <td>2018-08-01 12:00:00</td>\n",
+       "      <td>0 days</td>\n",
+       "      <td>850</td>\n",
+       "      <td>pressure</td>\n",
+       "      <td>0</td>\n",
+       "      <td>regular_ll</td>\n",
+       "      <td>meter / second</td>\n",
+       "    </tr>\n",
        "  </tbody>\n",
        "</table>\n",
        "</div>"
@@ -719,6 +730,7 @@
        "2                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
        "3                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
        "4                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
+       "5                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
        "\n",
        "   vertical.level vertical.level_type ensemble.member geography.grid_type  \\\n",
        "0            1000            pressure               0          regular_ll   \n",
@@ -726,13 +738,15 @@
        "2            1000            pressure               0          regular_ll   \n",
        "3             850            pressure               0          regular_ll   \n",
        "4             850            pressure               0          regular_ll   \n",
+       "5             850            pressure               0          regular_ll   \n",
        "\n",
        "  parameter.units  \n",
        "0          kelvin  \n",
        "1  meter / second  \n",
        "2  meter / second  \n",
        "3          kelvin  \n",
-       "4  meter / second  "
+       "4  meter / second  \n",
+       "5  meter / second  "
       ]
      },
      "execution_count": 7,
@@ -741,14 +755,14 @@
     }
    ],
    "source": [
-    "ds.head(extra_keys=\"parameter.units\")"
+    "fl.ls(extra_keys=\"parameter.units\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### tail()"
+    "## head()"
    ]
   },
   {
@@ -762,7 +776,7 @@
     "tags": []
    },
    "source": [
-    ":py:func:`~earthkit.data.core.fieldlist.FieldList.tail` displays the last 5 messages by default:"
+    ":py:meth:`~earthkit.data.core.fieldlist.FieldList.head` works in the same way as :py:meth:`~earthkit.data.core.fieldlist.FieldList.ls`  but it lists fields from the start of the fieldlist."
    ]
   },
   {
@@ -810,7 +824,7 @@
        "  <tbody>\n",
        "    <tr>\n",
        "      <th>0</th>\n",
-       "      <td>u</td>\n",
+       "      <td>t</td>\n",
        "      <td>2018-08-01 12:00:00</td>\n",
        "      <td>2018-08-01 12:00:00</td>\n",
        "      <td>0 days</td>\n",
@@ -821,44 +835,11 @@
        "    </tr>\n",
        "    <tr>\n",
        "      <th>1</th>\n",
-       "      <td>v</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>2</th>\n",
-       "      <td>t</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>3</th>\n",
        "      <td>u</td>\n",
        "      <td>2018-08-01 12:00:00</td>\n",
        "      <td>2018-08-01 12:00:00</td>\n",
        "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>4</th>\n",
-       "      <td>v</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
+       "      <td>1000</td>\n",
        "      <td>pressure</td>\n",
        "      <td>0</td>\n",
        "      <td>regular_ll</td>\n",
@@ -869,18 +850,12 @@
       ],
       "text/plain": [
        "  parameter.variable time.valid_datetime  time.base_datetime time.step  \\\n",
-       "0                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "1                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "2                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "3                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "4                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
+       "0                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
+       "1                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
        "\n",
        "   vertical.level vertical.level_type ensemble.member geography.grid_type  \n",
        "0            1000            pressure               0          regular_ll  \n",
-       "1            1000            pressure               0          regular_ll  \n",
-       "2             850            pressure               0          regular_ll  \n",
-       "3             850            pressure               0          regular_ll  \n",
-       "4             850            pressure               0          regular_ll  "
+       "1            1000            pressure               0          regular_ll  "
       ]
      },
      "execution_count": 8,
@@ -889,14 +864,20 @@
     }
    ],
    "source": [
-    "ds.tail(5)"
+    "fl.head(2)"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
-    "#### ls()"
+    "## tail()"
    ]
   },
   {
@@ -910,7 +891,7 @@
     "tags": []
    },
    "source": [
-    "By default :py:func:`~earthkit.data.fieldlist.FieldList.ls` lists all the fields:"
+    ":py:func:`~earthkit.data.core.fieldlist.FieldList.tail` works in the same way as :py:meth:`~earthkit.data.core.fieldlist.FieldList.ls`  but it lists fields from the end of the fieldlist. "
    ]
   },
   {
@@ -923,229 +904,6 @@
     },
     "tags": []
    },
-   "outputs": [
-    {
-     "data": {
-      "text/html": [
-       "<div>\n",
-       "<style scoped>\n",
-       "    .dataframe tbody tr th:only-of-type {\n",
-       "        vertical-align: middle;\n",
-       "    }\n",
-       "\n",
-       "    .dataframe tbody tr th {\n",
-       "        vertical-align: top;\n",
-       "    }\n",
-       "\n",
-       "    .dataframe thead th {\n",
-       "        text-align: right;\n",
-       "    }\n",
-       "</style>\n",
-       "<table border=\"1\" class=\"dataframe\">\n",
-       "  <thead>\n",
-       "    <tr style=\"text-align: right;\">\n",
-       "      <th></th>\n",
-       "      <th>parameter.variable</th>\n",
-       "      <th>time.valid_datetime</th>\n",
-       "      <th>time.base_datetime</th>\n",
-       "      <th>time.step</th>\n",
-       "      <th>vertical.level</th>\n",
-       "      <th>vertical.level_type</th>\n",
-       "      <th>ensemble.member</th>\n",
-       "      <th>geography.grid_type</th>\n",
-       "    </tr>\n",
-       "  </thead>\n",
-       "  <tbody>\n",
-       "    <tr>\n",
-       "      <th>0</th>\n",
-       "      <td>t</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>1</th>\n",
-       "      <td>u</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>2</th>\n",
-       "      <td>v</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>3</th>\n",
-       "      <td>t</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>4</th>\n",
-       "      <td>u</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>5</th>\n",
-       "      <td>v</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>850</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "  </tbody>\n",
-       "</table>\n",
-       "</div>"
-      ],
-      "text/plain": [
-       "  parameter.variable time.valid_datetime  time.base_datetime time.step  \\\n",
-       "0                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "1                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "2                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "3                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "4                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "5                  v 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "\n",
-       "   vertical.level vertical.level_type ensemble.member geography.grid_type  \n",
-       "0            1000            pressure               0          regular_ll  \n",
-       "1            1000            pressure               0          regular_ll  \n",
-       "2            1000            pressure               0          regular_ll  \n",
-       "3             850            pressure               0          regular_ll  \n",
-       "4             850            pressure               0          regular_ll  \n",
-       "5             850            pressure               0          regular_ll  "
-      ]
-     },
-     "execution_count": 9,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "ds.ls()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The number of fields to list can also be specified:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 10,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/html": [
-       "<div>\n",
-       "<style scoped>\n",
-       "    .dataframe tbody tr th:only-of-type {\n",
-       "        vertical-align: middle;\n",
-       "    }\n",
-       "\n",
-       "    .dataframe tbody tr th {\n",
-       "        vertical-align: top;\n",
-       "    }\n",
-       "\n",
-       "    .dataframe thead th {\n",
-       "        text-align: right;\n",
-       "    }\n",
-       "</style>\n",
-       "<table border=\"1\" class=\"dataframe\">\n",
-       "  <thead>\n",
-       "    <tr style=\"text-align: right;\">\n",
-       "      <th></th>\n",
-       "      <th>parameter.variable</th>\n",
-       "      <th>time.valid_datetime</th>\n",
-       "      <th>time.base_datetime</th>\n",
-       "      <th>time.step</th>\n",
-       "      <th>vertical.level</th>\n",
-       "      <th>vertical.level_type</th>\n",
-       "      <th>ensemble.member</th>\n",
-       "      <th>geography.grid_type</th>\n",
-       "    </tr>\n",
-       "  </thead>\n",
-       "  <tbody>\n",
-       "    <tr>\n",
-       "      <th>0</th>\n",
-       "      <td>t</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "    <tr>\n",
-       "      <th>1</th>\n",
-       "      <td>u</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>2018-08-01 12:00:00</td>\n",
-       "      <td>0 days</td>\n",
-       "      <td>1000</td>\n",
-       "      <td>pressure</td>\n",
-       "      <td>0</td>\n",
-       "      <td>regular_ll</td>\n",
-       "    </tr>\n",
-       "  </tbody>\n",
-       "</table>\n",
-       "</div>"
-      ],
-      "text/plain": [
-       "  parameter.variable time.valid_datetime  time.base_datetime time.step  \\\n",
-       "0                  t 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "1                  u 2018-08-01 12:00:00 2018-08-01 12:00:00    0 days   \n",
-       "\n",
-       "   vertical.level vertical.level_type ensemble.member geography.grid_type  \n",
-       "0            1000            pressure               0          regular_ll  \n",
-       "1            1000            pressure               0          regular_ll  "
-      ]
-     },
-     "execution_count": 10,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "ds.ls(2)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 11,
-   "metadata": {},
    "outputs": [
     {
      "data": {
@@ -1215,33 +973,51 @@
        "1             850            pressure               0          regular_ll  "
       ]
      },
-     "execution_count": 11,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds.ls(-2)"
+    "fl.tail(2)"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "### Inspecting fields"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "source": [
     "The simplest ways to inspect a field contents is to use the automatic display."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
-   "metadata": {},
+   "execution_count": 10,
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -1376,13 +1152,13 @@
        " }\n",
        "</style><div class=\"eh-description\">Field</div>\n",
        "<div>\n",
-       "<section class=\"eh-section>\n",
+       "<section class=\"eh-section\">\n",
        "<div class=\"eh-tabs-container\">\n",
        "<div class=\"eh-tabs-block\">\n",
        "<div class=\"eh-tabs\">\n",
        "\n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"201959c5-b2f7-4612-95d2-c59c3b311894\"  />\n",
-       "<label for=\"201959c5-b2f7-4612-95d2-c59c3b311894\" title=\"Keys in the data namespace\">data</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"0cb85c5a-8041-4aa5-8592-93c60bafb769\"  />\n",
+       "<label for=\"0cb85c5a-8041-4aa5-8592-93c60bafb769\" title=\"Keys in the data namespace\">data</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1399,8 +1175,8 @@
        "</table>\n",
        "</div>\n",
        "     \n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"fea4c0ac-60b1-4c98-8695-a919784eee03\" checked />\n",
-       "<label for=\"fea4c0ac-60b1-4c98-8695-a919784eee03\" title=\"Keys in the parameter namespace\">parameter</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"fffb1e1b-eef4-4312-a9ff-8a8770e404e3\" checked />\n",
+       "<label for=\"fffb1e1b-eef4-4312-a9ff-8a8770e404e3\" title=\"Keys in the parameter namespace\">parameter</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1417,8 +1193,8 @@
        "</table>\n",
        "</div>\n",
        "     \n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"1b01d3f2-bea4-4a72-86a0-886be5ea3903\"  />\n",
-       "<label for=\"1b01d3f2-bea4-4a72-86a0-886be5ea3903\" title=\"Keys in the time namespace\">time</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"7f09a7ff-7f01-41bc-9822-486328adc5ea\"  />\n",
+       "<label for=\"7f09a7ff-7f01-41bc-9822-486328adc5ea\" title=\"Keys in the time namespace\">time</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1435,8 +1211,8 @@
        "</table>\n",
        "</div>\n",
        "     \n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"09bebe2d-800c-4989-8959-d6c0f2699256\"  />\n",
-       "<label for=\"09bebe2d-800c-4989-8959-d6c0f2699256\" title=\"Keys in the vertical namespace\">vertical</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"7d0ad6f9-52e6-46f8-8fcf-95b2b720366d\"  />\n",
+       "<label for=\"7d0ad6f9-52e6-46f8-8fcf-95b2b720366d\" title=\"Keys in the vertical namespace\">vertical</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1453,8 +1229,8 @@
        "</table>\n",
        "</div>\n",
        "     \n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"1db6e30c-8ad8-45aa-9894-44c6532a12fb\"  />\n",
-       "<label for=\"1db6e30c-8ad8-45aa-9894-44c6532a12fb\" title=\"Keys in the ensemble namespace\">ensemble</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"39a0c094-7bc0-4005-9803-9ffde60b4029\"  />\n",
+       "<label for=\"39a0c094-7bc0-4005-9803-9ffde60b4029\" title=\"Keys in the ensemble namespace\">ensemble</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1471,8 +1247,8 @@
        "</table>\n",
        "</div>\n",
        "     \n",
-       "<input type=\"radio\" name=\"eh-tabs\" id=\"0a7ae308-22e4-4d4e-9b7d-e023a9ec56ba\"  />\n",
-       "<label for=\"0a7ae308-22e4-4d4e-9b7d-e023a9ec56ba\" title=\"Keys in the geography namespace\">geography</label>\n",
+       "<input type=\"radio\" name=\"eh-tabs\" id=\"bd226afc-e7b0-4cbe-a133-0863ee1b0d6c\"  />\n",
+       "<label for=\"bd226afc-e7b0-4cbe-a133-0863ee1b0d6c\" title=\"Keys in the geography namespace\">geography</label>\n",
        "<div class=\"tab\">\n",
        "<style type=\"text/css\">table.ek td {\n",
        "    vertical-align: top;\n",
@@ -1500,19 +1276,25 @@
        "Field(t, 2018-08-01 12:00:00, 2018-08-01 12:00:00, 0:00:00, 1000, pressure, 0, regular_ll)"
       ]
      },
-     "execution_count": 12,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
-    "ds[0]"
+    "fl[0]"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
    "outputs": [],
    "source": []
   }
diff --git a/docs/source/how-tos/grib/grib_overview.ipynb b/docs/source/how-tos/grib/grib_overview.ipynb
index 74706836..ab53ff9b 100644
--- a/docs/source/how-tos/grib/grib_overview.ipynb
+++ b/docs/source/how-tos/grib/grib_overview.ipynb
@@ -121,7 +121,7 @@
     "tags": []
    },
    "source": [
-    "A :ref:`GRIB <grib>` data object is represented by a :py:class:`~earthkit.data.core.fieldlist.FieldList` consisting of :py:class:`~earthkit.data.core.field.Field`\\s. When used in iteration the GRIB data is automatically loaded and released when going out of scope. As a result, during the iteration only one GRIB message at a time is kept in memory:"
+    "A :ref:`GRIB <grib>` data object is represented by a :py:class:`~earthkit.data.core.fieldlist.FieldList`, which is a collection of :py:class:`~earthkit.data.core.field.Field`\\s. When used in iteration the GRIB data is automatically loaded and released when going out of scope (assuming the default settings are used). As a result, during the iteration only one GRIB message at a time is kept in memory:"
    ]
   },
   {
diff --git a/docs/source/how-tos/xr_engine/xarray_engine_extra_dims.ipynb b/docs/source/how-tos/xr_engine/xarray_engine_extra_dims.ipynb
index 13755cf5..f0ae5601 100644
--- a/docs/source/how-tos/xr_engine/xarray_engine_extra_dims.ipynb
+++ b/docs/source/how-tos/xr_engine/xarray_engine_extra_dims.ipynb
@@ -215,7 +215,7 @@
    "id": "4e822233-94fc-4609-a3ce-68a2f0bbaf29",
    "metadata": {
     "editable": true,
-    "raw_mimetype": "text/x-rst",
+    "raw_mimetype": "text/restructuredtext",
     "slideshow": {
      "slide_type": ""
     },
@@ -1475,7 +1475,7 @@
    "id": "71685d1d-cb28-4f73-9dc0-f5be617b0fda",
    "metadata": {
     "editable": true,
-    "raw_mimetype": "text/x-rst",
+    "raw_mimetype": "text/restructuredtext",
     "slideshow": {
      "slide_type": ""
     },
diff --git a/docs/source/how-tos/xr_engine/xarray_engine_remapping.ipynb b/docs/source/how-tos/xr_engine/xarray_engine_remapping.ipynb
index 70096dbd..f7e2eed8 100644
--- a/docs/source/how-tos/xr_engine/xarray_engine_remapping.ipynb
+++ b/docs/source/how-tos/xr_engine/xarray_engine_remapping.ipynb
@@ -50,7 +50,7 @@
    "id": "71685d1d-cb28-4f73-9dc0-f5be617b0fda",
    "metadata": {
     "editable": true,
-    "raw_mimetype": "text/x-rst",
+    "raw_mimetype": "text/restructuredtext",
     "slideshow": {
      "slide_type": ""
     },
diff --git a/docs/source/skip_api_rules.py b/docs/source/skip_api_rules.py
index e1c7623f..f3b5743d 100644
--- a/docs/source/skip_api_rules.py
+++ b/docs/source/skip_api_rules.py
@@ -8,14 +8,67 @@
 #
 
 
+def _ends_with_any(name, suffixes):
+    for suffix in suffixes:
+        if name.endswith(suffix):
+            return True
+    return False
+
+
+_SKIP = {
+    "function": [
+        "sources.from_source",
+        "sources.from_source_internal",
+        "sources.from_source_lazily",
+        "sources.register",
+    ],
+    "class": [
+        "sources.SourceLoader",
+        "sources.SourceMaker",
+    ],
+    "data": [
+        "sources.get_source",
+    ],
+    "method": [
+        "core.fieldlist.FieldList.to_data_object",
+    ],
+}
+
+
 def _skip_api_items(app, what, name, obj, skip, options):
     # if what == "package":
     #     print(f"{name}[{what}]")
 
+    # print(f"{name}[{what}]")
     # if "ArrayLike" in name:
     #     print(f"Skipping {what} {name} {obj}")
 
     if what == "data" and ".ArrayLike" in name:
         skip = True
+    else:
+        s = _SKIP.get(what, [])
+        rel_name = name
+        if rel_name.startswith("earthkit.data."):
+            rel_name = rel_name[len("earthkit.data.") :]
+
+        if rel_name in s:
+            skip = True
+
+    # if name.startswith("earthkit.data.sources"):
+
+    #     if what == "class" and _ends_with_any(name, ["SourceLoader", "sources.SourceMaker"]):
+    #         skip = True
+
+    #     if what == "function" and _ends_with_any(
+    #         name,
+    #         [
+    #             "sources.from_source",
+    #             "sources.from_source_internal",
+    #             "sources.from_source_lazily",
+    #             "sources.get_source",
+    #             "sources.register",
+    #         ],
+    #     ):
+    #         skip = True
 
     return skip
diff --git a/src/earthkit/data/core/__init__.py b/src/earthkit/data/core/__init__.py
index 5907ad1a..df4f43ca 100644
--- a/src/earthkit/data/core/__init__.py
+++ b/src/earthkit/data/core/__init__.py
@@ -37,7 +37,7 @@ class Loader(Base):
     """Base class for all objects that can be loaded using a loader."""
 
     @abstractmethod
-    def cache_file(self, *args, **kwargs):
+    def _cache_file(self, *args, **kwargs):
         pass
 
     def mutate(self):
diff --git a/src/earthkit/data/core/field.py b/src/earthkit/data/core/field.py
index ce899528..215df314 100644
--- a/src/earthkit/data/core/field.py
+++ b/src/earthkit/data/core/field.py
@@ -61,7 +61,7 @@
 
 
 class _ComponentMaker:
-    """A factory class to delay import of component classes."""
+    """A factory class to delay the import of component classes."""
 
     def from_dict(self, name, *args, **kwargs):
         return self.default_cls(name).from_dict(*args, **kwargs)
@@ -111,7 +111,7 @@ def empty_object(self, name):
 class Field(Base):
     """A class to represent a field in Earthkit.
 
-    A Field is a horizontal slice of the atmosphere/hydrosphere a given time.
+    A Field is a horizontal slice of the atmosphere/hydrosphere at a given time.
 
     A Field object is composed of several components:
 
@@ -132,13 +132,73 @@ class Field(Base):
       :py:class:`~earthkit.data.field.handler.labels.SimpleLabels`)
 
     Field is not polymorphic, but its components are. The components are meant to be format
-    independent, but they can have format specific implementations. For example, the geography
-    component of a GRIB field can have a different implementation than the geography component of a
-    NetCDF field.
+    independent, but they can have format specific implementations with the same interface.
+    For example, the geography component of a GRIB field can have a different implementation
+    than the geography component of a NetCDF field.
 
+    Creating Fields
+    ----------------
     To create a new Field object use the factory methods: :meth:`from_dict`, :meth:`from_field`
     or :meth:`from_components`.
 
+    Values
+    ----------------
+
+    Metadata
+    ---------------
+    The metadata of a field can be divided into three categories:
+
+    - Core component metadata: the metadata that is stored in the components of the field.
+      Each component can be accessed by the corresponding property of the field, such as :obj:`time` for
+      the time component. The metadata of a component can be accessed by the methods of the component, e.g.
+
+      >>> field.time.valid_datetime()
+
+      The same metadata can also be accessed by the :meth:`get` method of the field with
+      the appropriate key, e.g.
+
+      >>> field.get("time.valid_datetime")  # equivalent to field.time.valid_datetime()
+
+    - Labels: the "labels" component of the field is a dictionary-like object that can store any
+      user defined key-value pairs. It can be accessed by the :obj:`labels` property of
+      the field, e.g.
+
+      >>> field.labels # returns the labels component of the field
+      >>> field.labels["my_key"] # returns the value of label "my_key"
+      >>> field.labels.get("my_key")  # equivalent to field.labels["my_key"]
+      >>> field.get("labels.my_key")  # equivalent to field.labels["my_key"]
+
+    - Raw metadata: the field can also store raw metadata that is not part of any component
+      or labels. For example if the field is created from a GRIB message the raw metadata
+      can include all the ecCodes GRIB keys. To access the raw metadata use the :meth:`get`
+      method by prefixing the raw metadata key with "metadata.", e.g.
+
+      >>> field.get("metadata.shortName")
+
+      The same can also be accessed by the :obj:`metadata` method of the field, which is
+      can only access the raw metadata of the field, e.g.
+
+      >>> field.metadata("shortName")
+      >>> field.metadata("metadata.shortName")
+
+      Please not that while :meth:`get` has a ``default`` argument to specify a default value when
+      the key is not found, the :meth:`metadata` method does not have this argument and will raise
+      a KeyError if the key is not found in the raw metadata.
+
+      Currently it is not possible to inspect what raw metadata keys are available in a field,
+      but this feature might be added in the future.
+
+
+    Modifying Fields
+    -----------------
+
+
+
+
+    Field arithmetic
+    ----------------
+    The Field class supports arithmetic operations such as addition, subtraction, multiplication
+
 
     """
 
@@ -258,7 +318,7 @@ def from_field(
         Returns
         -------
         Field
-            A new Field object with the components copied from the original field
+            A new Field with the components copied from the original field
             or specified in the keyword arguments.
         """
         _kwargs = {
@@ -291,7 +351,7 @@ def from_field(
 
     @classmethod
     def from_dict(cls, d):
-        r"""Create a Field object from a dictionary.
+        r"""Create a Field from a dictionary.
 
         Parameters
         ----------
@@ -302,7 +362,7 @@ def from_dict(cls, d):
         Returns
         -------
         Field
-            A new Field object created from the dictionary.
+            A new Field created from the dictionary.
         """
         if not isinstance(d, dict):
             raise TypeError("d must be a dictionary")
@@ -359,7 +419,7 @@ def from_components(
         proc=None,
         labels=None,
     ):
-        r"""Create a Field object from components.
+        r"""Create a Field from components.
 
         Parameters
         ----------
@@ -383,7 +443,7 @@ def from_components(
         Returns
         -------
         Field
-            A new Field object with the components copied from the original field
+            A new Field with the components copied from the original field
             or specified in the keyword arguments.
         """
         _kwargs = {
@@ -425,32 +485,68 @@ def ensemble(self):
 
     @property
     def time(self):
-        """Time: Return the time component of the field."""
+        """Return the time component of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.component.time.TimeBase`
+            The time component of the field.
+        """
         return self._components[_TIME].component
 
     @property
     def vertical(self):
-        """Vertical: Return the vertical component of the field."""
+        """Return the vertical component of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.component.vertical.VerticalBase`
+            The vertical component of the field.
+        """
         return self._components[_VERTICAL].component
 
     @property
     def parameter(self):
-        """Parameter: Return the parameter component of the field."""
+        """Return the parameter component of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.component.parameter.ParameterBase`
+            The parameter component of the field.
+        """
         return self._components[_PARAMETER].component
 
     @property
     def geography(self):
-        """Geography: Return the geography component of the field."""
+        """Return the geography component of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.component.geography.GeographyBase`
+            The geography component of the field.
+        """
         return self._components[_GEOGRAPHY].component
 
     @property
     def proc(self):
-        """Proc: Return the proc component of the field."""
+        """Return the proc component of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.component.proc.ProcBase`
+            The proc component of the field.
+        """
         return self._components[_PROC].component
 
     @property
     def labels(self):
-        """SimpleLabels: Return the labels of the field."""
+        """Return the labels of the field.
+
+        Returns
+        -------
+        :py:class:`~earthkit.data.field.handler.labels.SimpleLabels`
+            The labels of the field.
+        """
         return self._components[_LABELS]
 
     @property
@@ -463,7 +559,30 @@ def array_namespace(self):
 
     @property
     def values(self):
-        """array-like: Return the values of the field."""
+        """Return the values of the fields as a flat array.
+
+        Returns
+        -------
+        array-like
+            Flat array containing the field values without performing any copying or conversion. The underlying
+            array format of the field is used. For GRIB it is a numpy array.
+
+        See Also
+        --------
+        to_numpy
+        to_array
+
+        Examples
+        --------
+        >>> import earthkit.data as ekd
+        >>> f = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
+        >>> v = f.values
+        >>> v.shape
+        (209,)
+        >>> v[0][:3]
+        array([262.78027344, 267.44726562, 268.61230469])
+
+        """
         return self._components[_DATA].values
 
     @property
@@ -489,7 +608,7 @@ def to_numpy(self, flatten=False, dtype=None, copy=True, index=None):
         copy: bool
             When it is True a copy of the data is returned. Otherwise a view is returned where possible.
         index: ndarray indexing object, optional
-            The index of the values and to be extracted. When it
+            The index of the values to be extracted. When it
             is None all the values are extracted
 
         Returns
@@ -534,7 +653,7 @@ def to_array(
         device: str or None
             The device where the array will be allocated. When it is :obj:`None` the default device is used.
         index: array indexing object, optional
-            The index of the values and to be extracted. When it
+            The index of the values to be extracted. When it
             is None all the values are extracted.
 
         Returns
@@ -587,11 +706,16 @@ def data(self, keys=("lat", "lon", "value"), flatten=False, dtype=None, index=No
 
         Examples
         --------
+        How-to examples for the :meth:`data` method can be found in the following notebooks:
+
         - :ref:`/how-tos/grib/grib_lat_lon_value_ll.ipynb`
+        - :ref:`/how-tos/grib/grib_lat_lon_value_rgg.ipynb`
+
+        Other examples:
 
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test6.grib").to_fieldlist()
-        >>> d = ds[0].data()
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("file", "docs/how-tos/test6.grib").to_fieldlist()
+        >>> d = fl[0].data()
         >>> d.shape
         (3, 7, 12)
         >>> d[0, 0, 0]  # first latitude
@@ -600,7 +724,7 @@ def data(self, keys=("lat", "lon", "value"), flatten=False, dtype=None, index=No
         0.0
         >>> d[2, 0, 0]  # first value
         272.56417847
-        >>> d = ds[0].data(keys="lon")
+        >>> d = fl[0].data(keys="lon")
         >>> d.shape
         (7, 12)
         >>> d[0, 0]  # first longitude
@@ -886,12 +1010,12 @@ def get(
         Parameters
         ----------
         keys: str, list or tuple
-            Specify the key(s) to extract. Can be a single key (str) or multiple
+            Specify the field metadata keys to extract. Can be a single key (str) or multiple
             keys as a list/tuple of str. Keys are assumed to be of the form
-            "component.key". For example, "time.valid_datetime" or "parameter.name". It is also allowed to specify
-            just the component name like "time" or "parameter". In this case the corresponding component's
-            ``to_dict()`` method is called and its result is returned. For other keys, the method looks for them in
-            the private components (if any) and returns the value from the first private component that contains it.
+            "component.key". For example, "time.valid_datetime" or "parameter.name". Keys from the
+            raw metadata (if any) can be accessed using the "metadata.key" syntax.
+            For example, when a :obj:`Field` was created from a GRIB message, the ecCodes GRIB keys can
+            be accessed as "metadata.shortName" or "metadata.level".
         default: Any, None
             Specify the default value(s) for ``keys``. Returned when the given key
             is not found and ``raise_on_missing`` is False. When ``default`` is a single
@@ -903,6 +1027,15 @@ def get(
             It is only applied to keys returning a single value.
         raise_on_missing: bool
             When True, raises KeyError if any of ``keys`` is not found.
+        collections: str, list or tuple
+            Specify the metadata collections to extract. Can be a single collection (str) or multiple
+            collections as a list/tuple of str. A collection is a component of the field (e.g. "time",
+            "parameter", "geography", etc.) as a dictionary. It can also be a collection within the
+            raw "metadata" component. For example, when a :obj:`Field` was created from a GRIB
+            message, the ecCodes GRIB "namespaces" can be accessed as collections, e.g. "metadata.mars"
+            means the ecCodes GRIB "mars" namespace. The returned value for a collection is a dictionary with
+            the keys and values in the collection. To flatten the returned dictionary for a collection, use
+            the ``output==dict`` and ``flatten_dict=True`` options.
         output: type, str
             Specify the output type. Can be:
 
@@ -912,6 +1045,7 @@ def get(
             - list or "list": returns a list of values.
             - tuple or "tuple": returns a tuple of values.
             - dict or "dict": returns a dictionary with keys and their values.
+
             Other types are not supported.
         flatten_dict: bool
             When True and ``output`` is dict, if any of the values in the returned dict
@@ -938,6 +1072,67 @@ def get(
         KeyError
             If ``raise_on_missing`` is True and any of ``keys`` is not found.
 
+
+        Examples
+        --------
+        >>> import earthkit.data as ekd
+        >>> f = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
+        >>> f.get("parameter.variable")
+        '2t'
+
+        Get multiple keys as a list/tuple of values:
+
+        >>> f.get(["parameter.variable", "parameter.units"])
+        ['2t', 'K']
+        >>> f.get(("parameter.variable", "parameter.units"))
+        ('2t', 'K')
+
+        Get multiple keys as a dictionary:
+
+        >>> f.get(["parameter.variable", "parameter.units"], output="dict")
+        {'parameter.variable': '2t', 'parameter.units': 'K'}
+
+        Get collections:
+
+        >>> f.get(collections="time")
+        {'base_datetime': datetime.datetime(2020, 5, 13, 0, 0),
+        'step': datetime.timedelta(hours=0),
+        'valid_datetime': datetime.datetime(2020, 5, 13, 0, 0)}
+        >>> f.get(collections=["time", "parameter"])
+        [{'base_datetime': datetime.datetime(2020, 5, 13, 0, 0),
+        'step': datetime.timedelta(hours=0 ),
+        'valid_datetime': datetime.datetime(2020, 5, 13, 0, 0)},
+        {'variable': '2t',
+        'units': 'K'}]
+        >>> f.get(collections=["time", "parameter"], dict=True)
+        {'time': {'base_datetime': datetime.datetime(2020, 5, 13, 0, 0),
+        'step': datetime.timedelta(hours=0 ),
+        'valid_datetime': datetime.datetime(2020, 5, 13, 0, 0)},
+        'parameter': {'variable': '2t',
+        'units': 'K'}}
+
+        Use ``output=dict`` and ``flatten_dict=True`` to flatten the returned dictionary for collections:
+
+        >>> f.get(collections=["time"], output="dict", flatten_dict=True)
+        {'time.base_datetime': datetime.datetime(2020, 5, 13, 0, 0),
+        'time.step': datetime.timedelta(hours=0),
+        'time.valid_datetime': datetime.datetime(2020, 5, 13, 0, 0)}
+
+        Get the ecCodes GRIB "mars" namespace as a collection from the raw metadata
+        (result trimmed for brevity):
+        >>> f.get(collections="metadata.mars", output="dict")
+        {"metadata.mars": {'class': 'od', 'date': 20200513, 'expver': '0001'}}
+
+        Mix keys and collections (result trimmed for brevity):
+
+        >>> f.get(keys="metadata.shortName", collections="metadata.mars", output="dict")
+        {'metadata.shortName': '2t', 'metadata.mars': {'class': 'od', 'date': 20200513, 'expver': '0001'}}
+        >>> f.get(keys="metadata.shortName", collections="metadata.mars", output="dict", flatten_dict=True)
+        {'metadata.shortName': '2t',
+        'metadata.mars.class': 'od',
+        'metadata.mars.date': 20200513,
+        'metadata.mars.expver': '0001'}
+
         """
         if not keys and not collections:
             raise ValueError("At least one key or collection must be specified.")
@@ -948,14 +1143,6 @@ def get(
             astype=astype,
         )
 
-        # if collections:
-        #     if isinstance(collections, str):
-        #         keys = [keys]
-        #     elif isinstance(keys, tuple):
-        #         keys = list(keys)
-        #     for collection in collections:
-        #         keys.append(collection + ".*")
-
         if output == "auto":
             if keys_arg_type is not str:
                 output = keys_arg_type
@@ -991,7 +1178,63 @@ def metadata(
         remapping=None,
         patch=None,
     ):
+        r"""Return the raw metadata values.
+
+        Parameters
+        ----------
+        keys: str, list or tuple
+            Specify the raw metadata keys to extract. Can be a single key (str) or multiple
+            keys as a list/tuple of str. Keys can be optionally prefixed with "metadata.". For example,
+            if the raw metadata has the key "shortName", it can also be specified
+            as "metadata.shortName".
+        astype: type as str, int or float
+            Return type for ``keys``.  When ``astype`` is a single type, it is used for
+            all the keys. Otherwise it must be a list/tuple of the same length as ``keys``.
+            It is only applied to keys returning a single value.
+        output: type, str
+            Specify the output type. Can be:
+
+            - "auto" (default):
+                - when ``keys`` is a str returns a single value
+                - when ``keys`` is a list/tuple returns a list/tuple of values
+            - list or "list": returns a list of values.
+            - tuple or "tuple": returns a tuple of values.
+            - dict or "dict": returns a dictionary with keys and their values.
+            Other types are not supported.
+        remapping: dict, optional
+            Create new metadata keys from existing ones. E.g. to define a new
+            key "param_level" as the concatenated value of the "param" and "level" keys use::
+
+                remapping={"param_level": "{param}{level}"}
+
+        patch: dict, optional
+            A dictionary of patch to be applied to the returned values.
 
+        Returns
+        -------
+        single value, list, tuple or dict
+            The values for the specified ``keys``. The structure of the returned value(s) depends on the ``output``
+            and ``flatten_dict`` parameters.
+
+        Raises
+        ------
+        KeyError
+            If any of ``keys`` is not found in the raw metadata.
+
+
+        Examples
+        --------
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test.grib").to_fieldlist()
+        >>> f = fl[0]
+        >>> f.metadata("shortName")
+        '2t'
+        >>> f.metadata(["shortName", "units"])
+        ['2t', 'K']
+        >>> f.metadata(("shortName", "units"))
+        ('2t', 'K')
+
+        """
         if isinstance(keys, str) and not keys.startswith("metadata."):
             keys = "metadata." + keys
         else:
@@ -1010,7 +1253,7 @@ def metadata(
         )
 
     def set(self, *args, **kwargs):
-        """Return a new Field with the specified metadata keys set to the given values.
+        """Return a new field with the specified metadata keys set to the given values.
 
         Parameters
         ----------
@@ -1025,7 +1268,7 @@ def set(self, *args, **kwargs):
         Returns
         -------
         Field
-            A new Field object with the specified metadata keys set to the given values.
+            A new field with the specified metadata keys set to the given values.
 
         """
         kwargs = kwargs.copy()
@@ -1085,11 +1328,23 @@ def to_target(self, target, *args, **kwargs):
         Parameters
         ----------
         target: object
-            The target object to write the field into.
+            The :ref:`target <data-target-objects>` to write the field into.
         *args: tuple
             Positional arguments used to specify the target object.
         **kwargs: dict, optional
             Other keyword arguments used to write the field into the target object.
+
+        See Also
+        --------
+        :ref:`targets`
+        :ref:`data-target-objects`
+
+        Examples
+        --------
+        How-to examples for the :meth:`to_target` method can be found in the following notebooks:
+
+        - :ref:`/how-tos/target/file_target.ipynb`
+        - :ref:`/how-tos/target/grib_to_file_target.ipynb`
         """
         from earthkit.data.targets import to_target
 
@@ -1147,6 +1402,20 @@ def to_xarray(self, *args, **kwargs):
         return self._dispatch_to_fieldlist_method("to_xarray", *args, **kwargs)
 
     def to_pandas(self, *args, **kwargs):
+        """Convert the Field into a Pandas DataFrame.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments passed to :obj:`FieldList.to_pandas`.
+        **kwargs: dict, optional
+            Other keyword arguments passed to :obj:`FieldList.to_pandas`.
+
+        Returns
+        -------
+        Pandas DataFrame
+
+        """
         return self._dispatch_to_fieldlist_method("to_pandas", *args, **kwargs)
 
     def _dump_component(self, component="all", *, filter=None, prefix_keys=False, unwrap_single=True):
@@ -1213,8 +1482,7 @@ def describe(self, component=all, filter=None, **kwargs):
             have a special meaning:
 
             - :obj:`all`: all the available components will be used.
-            - None or empty str: all the available keys will be used
-                (without a component qualifier)
+
 
         **kwargs: dict, optional
             Other keyword arguments used for testing only
@@ -1222,8 +1490,8 @@ def describe(self, component=all, filter=None, **kwargs):
         Returns
         -------
         NamespaceDump
-            Dict-like object with one item per namespace. In a Jupyter notebook represented
-            as a tabbed interface to browse the dump contents.
+            Dict-like object with one item s per component. In a Jupyter notebook represented
+            as a tabbed interface to browse the dump con stents.
 
 
         See Also
@@ -1262,33 +1530,103 @@ def describe(self, component=all, filter=None, **kwargs):
 
     @property
     def default_ls_keys(self):
+        """list: Return the default keys to be used for the :meth:`ls` method."""
         return _LS_KEYS
 
-    def ls(self, *args, **kwargs):
-        r"""Generate a list-like summary using a set of metadata keys.
+    def ls(
+        self,
+        n=None,
+        keys="default",
+        extra_keys=None,
+        collections=None,
+    ):
+        r"""Generate a one row summary of the Field using a set of metadata keys.
 
         Parameters
         ----------
-        *args: tuple
-            Positional arguments passed to :obj:`FieldList.ls`.
-        **kwargs: dict, optional
-            Other keyword arguments passed to :obj:`FieldList.ls`.
+        n: int, None
+            This parameter is ignored since the summary is generated for a single field. It is
+            only used for compatibility with the
+            :py:meth:`earthkit.data.core.fieldlist.FieldList.ls` method.
+        keys: list of str, dict, None
+            The metadata keys to extract. If ``keys="default"``, a built-in default set of keys is used.
+            To specify a column title for each key in the output use a dict as a mapping from the keys to the
+            column titles.
+        extra_keys: list of str, dict, None
+            List of additional keys on top of ``keys``. To specify a column title for each key in the output
+            use a dict as a mapping from the keys to the column titles.
+        collections: str, list of str, None
+            The collections to extract. Can be a single collection (str) or multiple collections as a
+            list of str. A collection is a component of the field (e.g. "time", "parameter",
+            "geography", etc.) as a dictionary. It can also be a collection within the raw
+            "metadata" component. For example, when a :obj:`Field` was created from a GRIB message, the
+            ecCodes GRIB "namespaces" can be accessed as collections, e.g. "metadata.mars" means
+            the ecCodes GRIB "mars" namespace.
 
         Returns
         -------
         Pandas DataFrame
-            DataFrame with one row.
+            DataFrame with one row per :obj:`Field`.
+
+        See Also
+        --------
+        head
+        tail
 
         """
-        return self._dispatch_to_fieldlist_method("ls", *args, **kwargs)
+        return self._dispatch_to_fieldlist_method(
+            "ls", n=None, keys=keys, extra_keys=extra_keys, collections=collections
+        )
 
     def head(self, *args, **kwargs):
-        r"""Generate a head summary of the Field."""
-        return self._dispatch_to_fieldlist_method("head", *args, **kwargs)
+        r"""Generate a one row summary of the Field using a set of metadata keys.
+
+        Same as calling :obj:`ls`.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments passed to :obj:`ls`.
+        **kwargs: dict, optional
+            Other keyword arguments passed to :obj:`ls`.
+
+        Returns
+        -------
+        Pandas DataFrame
+            See :obj:`ls`.
+
+        See Also
+        --------
+        ls
+        tail
+
+        """
+        return self.ls("head", *args, **kwargs)
 
     def tail(self, *args, **kwargs):
-        r"""Generate a tail summary of the Field."""
-        return self._dispatch_to_fieldlist_method("tail", *args, **kwargs)
+        r"""Generate a one row summary of the Field using a set of metadata keys.
+
+        Same as calling :obj:`ls`.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments passed to :obj:`ls`.
+        **kwargs: dict, optional
+            Other keyword arguments passed to :obj:`ls`.
+
+        Returns
+        -------
+        Pandas DataFrame
+            See :obj:`ls`.
+
+        See Also
+        --------
+        ls
+        tail
+
+        """
+        return self.ls("tail", *args, **kwargs)
 
     def message(self):
         r"""Return a buffer containing the encoded message for Fields generated from a message based format (e.g. GRIB).
@@ -1346,11 +1684,73 @@ def _normalise_key_values(**kwargs):
         r"""Normalise the selection input for :meth:`FieldList.sel`."""
         return kwargs
 
-    def sel(self, *args, **kwargs):
-        pass
+    # def sel(self, *args, **kwargs):
+    #     r"""Check if a field matches the given selection criteria.
+
+    #     Parameters
+    #     ----------
+    #     *args: tuple
+    #         Positional arguments specifying the filter conditions as a dict.
+    #         Both single or multiple keys are allowed to use. When multiple filter conditions
+    #         are specified, they are combined with a logical AND operator. Each metadata key in
+    #         the filter conditions can specify the following type of filter values:
+
+    #         - single value::
+
+    #             f.sel({parameter.variable: "t"})
+
+    #         - list of values::
+
+    #             f.sel({parameter.variable: ["u", "v"]})
+
+    #         - slice of values (defines a closed interval, so treated as inclusive of both the start
+    #         and stop values, unlike normal Python indexing). The following example filters the fields
+    #         with "vertical.level" between 300 and 500 inclusively::
+
+    #             f.sel({vertical.level: slice(300, 500)})
+
+    #         Date and time related keys from the "time" field component are automatically normalised
+    #         for comparison. This is also applied to the following keys from the
+    #         raw metadata: "metadata.base_datetime", "metadata.valid_datetime" and "metadata.step_timedelta".
+
+    #         For example, when filtering by "time.valid_datetime" the following calls are equivalent:
+
+    #         >>> f.sel({ "time.valid_datetime": "2018-08-01T12:00:00"})
+    #         >>> f.sel({ "time.valid_datetime": "2018080112"})
+    #         >>> f.sel({ "time.valid_datetime": 2018080112})
+    #         >>> f.sel({ "time.valid_datetime": datetime(2018, 8, 1, 12, 0) })
+
+    #         Similarly, when filtering by "time.step" the following calls are equivalent (values are assumed
+    #         to be in hours when the unit is not specified):
+
+    #         >>> f.sel({ "time.step": "6h"})
+    #         >>> f.sel({ "time.step": 6})
+    #         >>> f.sel({ "time.step": "360m"})
+    #         >>> f.sel({ "time.step": timedelta(hours=6)})
+
+    #     remapping: dict
+    #         Define new metadata keys from existing ones to use in ``*args`` and ``**kwargs``.
+    #         E.g. to define a new key "param_level" as the concatenated value of
+    #         the "parameter.variable" and "vertical.level" keys use::
+
+    #         >>> remapping={"param_level": "{parameter.variable}{vertical.level}"}
+
+    #     **kwargs: dict, optional
+    #         Other keyword arguments specifying the filter conditions.
+
+    #     Returns
+    #     -------
+    #     Field or None
+    #         Returns the field itself if it matches the selection criteria, otherwise returns None.
+    #     """
+    #     res = self._dispatch_to_fieldlist_method("sel", *args, **kwargs)
+
+    #     if res and len(res) == 1:
+    #         return self
+    #     return None
 
-    def order_by(self, *args, **kwargs):
-        pass
+    # def order_by(self, *args, **kwargs):
+    #     pass
 
     def _unary_op(self, oper):
         v = oper(self.values)
diff --git a/src/earthkit/data/core/fieldlist.py b/src/earthkit/data/core/fieldlist.py
index add31375..6f8be7ff 100644
--- a/src/earthkit/data/core/fieldlist.py
+++ b/src/earthkit/data/core/fieldlist.py
@@ -24,9 +24,10 @@ def create_fieldlist(fields=None):
 
     Returns
     -------
-    :class:`~earthkit.data.core.fieldlist.FieldList`
-        A fieldlist object containing the given fields.
-
+    :class:`~earthkit.data.indexing.simple.SimpleFieldList`, :class:`~earthkit.data.indexing.empty.EmptyFieldList`
+        A fieldlist object containing the given fields. When ``fields`` is None or empty, an
+        :class:`~earthkit.data.indexing.empty.EmptyFieldList` is returned. Otherwise a
+        :class:`~earthkit.data.indexing.simple.SimpleFieldList` is returned.
 
     """
     from earthkit.data.indexing.empty import EmptyFieldList
@@ -41,7 +42,41 @@ def create_fieldlist(fields=None):
 class FieldList(Source, Encodable):
     """Base class for a FieldList.
 
-    A FieldList is a collection of Fields. It provides methods to access the field values and metadata.
+    A FieldList is a collection of Fields. It is an immutable object that provides methods to access
+    the field values and metadata and allows iteration over the fields. It also provides methods to select
+    a subset of fields based on their metadata.
+
+    Implementations
+    ---------------
+    FieldList is an abstract class. All the concrete implementations are derived from
+    :class:`~earthkit.data.indexing.indexed.IndexFieldListBase`. This class is formed by
+    multiple inheritance with the :class:`~earthkit.data.core.index.Index` class that implements
+    indexing capabilities without specifying the actual indexed objects. It is still an abstract
+    class but provides concrete implementations for many of the FieldList methods. It also
+    implements fieldlist arithmetic.
+
+    Some of the concrete implementations are:
+
+    - :class:`~earthkit.data.indexing.empty.EmptyFieldList` is a FieldList implementation that
+      contains no fields. It can be used when building fieldlists by concatenation.
+      of a FieldList with no fields. It can be used when building fieldlists by concatenation.
+    - :class:`~earthkit.data.indexing.simple.SimpleFieldList`: a FieldList containing a list fields.
+      Can be created from a list of fields by :obj:`from_fields` or the top
+      level earthkit-data :obj:`create_fieldlist` factory function.
+    - :class:`~earthkit.data.readers.grib.file.GribFieldListInFile`: a FieldList containing fields
+      from a GRIB file.
+    - :class:`~earthkit.data.readers.xarray.fieldlist.XArrayFieldList`: a FieldList containing fields
+      from an xarray Dataset.
+
+
+    Creating a FieldList
+    ---------------------
+    A FieldList can be created by calling the :func:`to_fieldlist` method of a high level data object,
+    see :ref:`data-object` for more details.
+
+    A :class:`~earthkit.data.indexing.simple.SimpleFieldList` can also be created directly from
+    a list of fields by calling the :func:`from_fields` method, or alternatively by calling the
+    top level earthkit-data :func:`create_fieldlist` factory function.
     """
 
     @abstractmethod
@@ -54,16 +89,20 @@ def __len__(self):
 
     @staticmethod
     def from_fields(fields=None):
-        r"""Create a :class:`SimpleFieldList`.
+        r"""Create a fieldlist from the given fields.
 
         Parameters
         ----------
-        fields: iterable, Field, None
-            Iterable of :obj:`Field` objects.
+        fields: iterable, :class:`~earthkit.data.core.field.Field`, None
+            Iterable of :class:`~earthkit.data.core.field.Field` objects. When it is None or empty,
+            an empty fieldlist is returned.
 
         Returns
         -------
-        :class:`SimpleFieldList`
+        :class:`~earthkit.data.indexing.simple.SimpleFieldList`, :class:`~earthkit.data.indexing.empty.EmptyFieldList`
+            A fieldlist object containing the given fields. When ``fields`` is None or empty, an
+            :class:`~earthkit.data.indexing.empty.EmptyFieldList` is returned. Otherwise a
+            :class:`~earthkit.data.indexing.simple.SimpleFieldList` is returned.
 
         """
         return create_fieldlist(fields)
@@ -71,21 +110,30 @@ def from_fields(fields=None):
     @property
     @abstractmethod
     def values(self):
-        """array-like: Get all the fields' values as a 2D array. It is formed as the array of
-        :obj:`Field.values <earthkit.data.core.field.Field.values>` per field.
+        """Return the values of all the fields as a 2D array.
+
+        Returns
+        -------
+        array-like
+            Array containing the values of all the fields. The return array is
+            formed as the array of the flattened values extracted from each field by
+            :obj:`Field.values <earthkit.data.core.field.Field.values>`.
 
         See Also
         --------
+        earthkit.data.core.field.Field.values
         to_array
 
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test.grib")
-        >>> for f in ds:
+        Examples
+        --------
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test.grib").to_fieldlist()
+        >>> for f in fl:
         ...     print(f.values.shape)
         ...
         (209,)
         (209,)
-        >>> v = ds.values
+        >>> v = fl.values
         >>> v.shape
         (2, 209)
         >>> v[0][:3]
@@ -95,50 +143,88 @@ def values(self):
         pass
 
     @abstractmethod
-    def to_numpy(self, **kwargs):
-        r"""Return all the fields' values as an array.
-
-        It is formed as the array of the :obj:`earthkit.data.core.field.Field.to_array` values per field.
+    def to_numpy(self, flatten=False, dtype=None, copy=True, index=None):
+        r"""Return the values of all the fields as a Numpy array.
 
         Parameters
         ----------
-        **kwargs: dict, optional
-            Keyword arguments passed to :obj:`earthkit.data.core.field.Field.to_array`
+        flatten: bool
+            When it is True the values are flattened per field. Otherwise an ndarray with the field's
+            :obj:`shape` is returned per field.
+        dtype: str, numpy.dtype or None
+            Typecode or data-type of the array. When it is :obj:`None` the default
+            type used by the underlying data accessor of the field is used. For GRIB it is ``float64``.
+        copy: bool
+            When it is True a copy of the data values per field is returned. Otherwise a view
+            is returned where possible.
+        index: ndarray indexing object, optional
+            The index of the values to be extracted per field. When it is None all the values are extracted.
 
         Returns
         -------
-        array-like
-            Array containing the field values.
+        ndarray
+            Array containing the field values. It is formed as the array of values extracted by
+            :obj:`earthkit.data.core.field.Field.to_numpy` per field.
 
         See Also
         --------
-        :obj:`earthkit.data.core.field.Field.to_array`
+        :obj:`earthkit.data.core.field.Field.to_numpy`
         values
-        to_numpy
+        to_array
+
+        Examples
+        --------
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_array_namespace.ipynb`
+
         """
         pass
 
     @abstractmethod
     def to_array(self, **kwargs):
-        r"""Return all the fields' values as an array.
+        r"""Return the values of all the fields as an array.
 
         It is formed as the array of the :obj:`earthkit.data.core.field.Field.to_array` values per field.
 
         Parameters
         ----------
-        **kwargs: dict, optional
-            Keyword arguments passed to :obj:`earthkit.data.core.field.Field.to_array`
+        flatten: bool
+            When it is True the values are flattened per field. Otherwise an array with the field's
+            :obj:`shape` is returned per field.
+        dtype: str, array.dtype or None
+            Typecode or data-type of the array. When it is :obj:`None` the default
+            type used by the underlying data accessor is used. For GRIB it is ``float64``.
+        copy: bool
+            When it is True a copy of the data values per field is returned. Otherwise a view
+            is returned where possible.
+        array_namespace: str, array_namespace or None
+            The array namespace to be used. When it is :obj:`None` the underlying array format
+            of the field is used. For GRIB it is "numpy".
+        device: str or None
+            The device where the array will be allocated. When it is :obj:`None` the default device is used.
+        index: array indexing object, optional
+            The index of the values to be extracted per field. When it is None all the values are extracted.
+            is None all the values are extracted.
 
         Returns
         -------
         array-like
-            Array containing the field values.
+            Array containing the field values. It is formed as the array of values extracted by
+            :obj:`earthkit.data.core.field.Field.to_array` per field.
 
         See Also
         --------
         :obj:`earthkit.data.core.field.Field.to_array`
         values
         to_numpy
+
+        Examples
+        --------
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_array_namespace.ipynb`
+
         """
         pass
 
@@ -194,13 +280,18 @@ def data(
 
         Examples
         --------
+        How-to examples:
+
         - :ref:`/how-tos/grib/grib_lat_lon_value_ll.ipynb`
+        - :ref:`/how-tos/grib/grib_lat_lon_value_rgg.ipynb`
 
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test6.grib")
-        >>> len(ds)
+        More examples:
+
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test6.grib").to_fieldlist()
+        >>> len(fl)
         6
-        >>> d = ds.data()
+        >>> d = fl.data()
         >>> d.shape
         (8, 7, 12)
         >>> d[0, 0, 0]  # first latitude
@@ -210,19 +301,31 @@ def data(
         >>> d[2:, 0, 0]  # first value per field
         array([272.56417847,  -6.28688049,   7.83348083, 272.53916931,
                 -4.89837646,   8.66096497])
-        >>> d = ds.data(keys="lon")
+        >>> d = fl.data(keys="lon")
         >>> d.shape
         (1, 7, 12)
         >>> d[0, 0, 0]  # first longitude
         0.0
 
-
         """
         pass
 
     @property
     @abstractmethod
     def geography(self):
+        """Return the geography of the FieldList.
+
+        Returns
+        -------
+        GeographyBase
+            If the fields in the FieldList have the same grid geometry, the returned geography is the one of
+            the first field. Otherwise an error is raised.
+
+        Raises
+        ------
+        ValueError
+            When not all the fields have the same grid geometry or the FieldList is empty.
+        """
         pass
 
     @abstractmethod
@@ -245,11 +348,10 @@ def get(
         keys: str, list, tuple
             Specify the field metadata keys to extract. Can be a single key (str) or multiple
             keys as a list/tuple of str. Keys are assumed to be of the form
-            "component.key". For example, "time.valid_datetime" or "parameter.name". It is also allowed to specify
-            just the component name like "time" or "parameter". In this case the corresponding component's
-            ``to_dict()`` method is called and its result is returned. For other keys, the method looks for them in
-            the private components of the fields (if any) and returns the value from the first private component
-            that contains it.
+            "component.key". For example, "time.valid_datetime" or "parameter.name". Keys from the
+            raw field metadata (if any) can be accessed using the "metadata.key" syntax.
+            For example, when a :obj:`Field` was created from a GRIB message, the ecCodes GRIB keys can
+            be accessed as "metadata.shortName" or "metadata.level".
         default: Any, None
             Specify the default value(s) for ``keys``. Returned when the given key
             is not found and ``raise_on_missing`` is False. When ``default`` is a single
@@ -261,7 +363,7 @@ def get(
         raise_on_missing: bool
             When True, raises KeyError if any of ``keys`` is not found.
         output: type, str
-            Specify the output structure type in conjunction with ``group_by_key``.  When ``group_by`` is False
+            Specify the output structure type in conjunction with ``group_by_key``. When ``group_by`` is False
             (default) the output is a list with one item per field and ``output`` has the following effect
             on the items:
 
@@ -272,16 +374,16 @@ def get(
             - tuple or "tuple": returns a tuple of values per field.
             - dict or "dict": returns a dictionary with keys and their values per field.
 
-            When ``group_by_key`` is True the output is grouped by key as follows and return an object with
-            one item per key. The item contains the list of values for that key from all the fields. When
-            ``output`` is dict a dict is returned otherwise list.
+            When ``group_by_key`` is True the output is grouped by key and return an object with
+            one item per key. The item per key contains the list of values for that key from all the
+            fields. When ``output`` is "dict" a dict is returned, otherwise a list.
 
         group_by_key: bool
             When True the output is grouped by key as described in ``output``.
         flatten_dict: bool
             When True and ``output`` is dict, for each field if any of the values in the returned dict
             is itself a dict, it is flattened to depth 1 by concatenating the keys with a dot. For example, if
-            the returned dict is ``{"a": {"x": 1, "y": 2}, "b": 3}``, it becomes ``{"a.x": 1, "a.y": 2, "b": 3}``.
+            the returned dict is ``{"a": {"x": 1, "y": 2}, "b": 3}``, it becomes ``{"a.x": 1, " a.y": 2, "b": 3}``.
             This option is ignored when ``output`` is not dict.
         remapping: dict, optional
             Create new metadata keys from existing ones. E.g. to define a new
@@ -306,13 +408,13 @@ def get(
 
         Examples
         --------
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test.grib")
-        >>> ds.get("parameter.variable")
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test.grib").to_fieldlist()
+        >>> fl.get("parameter.variable")
         ['2t', 'msl']
-        >>> ds.get(["parameter.variable", "parameter.units"])
+        >>> fl.get(["parameter.variable", "parameter.units"])
         [('2t', 'K'), ('msl', 'Pa')]
-        >>> ds.get(("parameter.variable", "parameter.units"))
+        >>> fl.get(("parameter.variable", "parameter.units"))
         [['2t', 'K'], ['msl', 'Pa']]
 
         """
@@ -320,7 +422,7 @@ def get(
 
     @abstractmethod
     def metadata(self, *args, **kwargs):
-        r"""Return the metadata values for each field.
+        r"""Return the raw metadata values for each field.
 
         Parameters
         ----------
@@ -338,13 +440,13 @@ def metadata(self, *args, **kwargs):
 
         Examples
         --------
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test.grib")
-        >>> ds.metadata("param")
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test.grib").to_fieldlist()
+        >>> fl.metadata("param")
         ['2t', 'msl']
-        >>> ds.metadata("param", "units")
+        >>> fl.metadata("param", "units")
         [('2t', 'K'), ('msl', 'Pa')]
-        >>> ds.metadata(["param", "units"])
+        >>> fl.metadata(["param", "units"])
         [['2t', 'K'], ['msl', 'Pa']]
 
         """
@@ -353,42 +455,55 @@ def metadata(self, *args, **kwargs):
     def set(self, *args, **kwargs):
         r"""Set the metadata values for each field.
 
+        All the arguments are passed to :py:meth:`earthkit.data.core.field.Field.set` for each field in the fieldlist.
+
         Parameters
         ----------
         *args: tuple
-            Positional arguments defining the metadata keys and values. Passed to
-            :obj:`Field.set_metadata() <earthkit.data.core.field.Field.set_metadata>`
+            Positional arguments defining the metadata keys and values.
         **kwargs: dict, optional
-            Keyword arguments passed to
-            :obj:`Field.set_metadata() <earthkit.data.core.field.Field.set_metadata>`
+            Keyword arguments defining the metadata keys and values.
+
+        Returns
+        -------
+        FieldList
+            New FieldList with the updated metadata values.
+
+        See Also
+        --------
+        :py:meth:`earthkit.data.core.field.Field.set`
+
         """
         pass
 
     @abstractmethod
-    def ls(self, n=None, keys=None, extra_keys=None, namespace=None):
+    def ls(self, n=None, keys="default", extra_keys=None, collections=None):
         r"""Generate a list like summary using a set of metadata keys.
 
         Parameters
         ----------
         n: int, None
-            The number of :obj:`Field`\ s to be
+            The number of fields to be
             listed. None means all the fields, ``n > 0`` means fields from the front, while
             ``n < 0`` means fields from the back of the fieldlist.
         keys: list of str, dict, None
-            Metadata keys used when ``namespace`` is None. If ``keys`` is None the following default
-            set of keys will be used:  "centre", "shortName", "typeOfLevel", "level", "dataDate",
-            "dataTime", "stepRange", "dataType", "number", "gridType". To specify a column title for each
-            key in the output use a dict.
+            The metadata keys to extract. If ``keys="default"``, a built-in default set of keys is used.
+            To specify a column title for each key in the output use a dict as a mapping from the keys to the
+            column titles.
         extra_keys: list of str, dict, None
-            List of additional keys. To specify a column title for each key in the output
-            use a dict.
-        namespace: str, list of str, None
-            The namespace(s) to choose the ``keys`` from. When it is set ``keys`` are omitted.
+            List of additional keys on top of ``keys``. To specify a column title for each key in the output
+            use a dict as a mapping from the keys to the column titles.
+        collections: str, list of str, None
+            The collections to extract. Can be a single collection (str) or multiple collections as a list of str.
+            A collection is a component of the field (e.g. "time", "parameter", "geography", etc.) as a dictionary.
+            It can also be a collection within the raw "metadata" component. For example, when a :obj:`Field` was
+            created from a GRIB message, the ecCodes GRIB "namespaces" can be accessed as collections,
+            e.g. "metadata.mars" means the ecCodes GRIB "mars" namespace.
 
         Returns
         -------
         Pandas DataFrame
-            DataFrame with one row per :obj:`Field`.
+            DataFrame with one row per :py:class:`~earthkit.data.core.field.Field`.
 
         See Also
         --------
@@ -400,20 +515,21 @@ def ls(self, n=None, keys=None, extra_keys=None, namespace=None):
 
     @abstractmethod
     def head(self, n=5, **kwargs):
-        r"""Generate a list like summary of the first ``n`` :obj:`Field`\ s.
+        r"""Generate a list like summary of the first ``n`` fields.
+
         Same as calling :obj:`ls` with ``n``.
 
         Parameters
         ----------
         n: int, None
-            The number of messages (``n`` > 0) to be printed from the front.
+            The number of fields (``n`` > 0) to be printed from the front.
         **kwargs: dict, optional
             Other keyword arguments passed to :obj:`ls`.
 
         Returns
         -------
         Pandas DataFrame
-            See  :obj:`ls`.
+            See :obj:`ls`.
 
         See Also
         --------
@@ -426,24 +542,25 @@ def head(self, n=5, **kwargs):
 
         .. code-block:: python
 
-            ds.head()
-            ds.head(5)
-            ds.head(n=5)
-            ds.ls(5)
-            ds.ls(n=5)
+            fl.head()
+            fl.head(5)
+            fl.head(n=5)
+            fl.ls(5)
+            fl.ls(n=5)
 
         """
         pass
 
     @abstractmethod
     def tail(self, n=5, **kwargs):
-        r"""Generate a list like summary of the last ``n`` :obj:`Field`\ s.
+        r"""Generate a list like summary of the last ``n`` fields.
+
         Same as calling :obj:`ls` with ``-n``.
 
         Parameters
         ----------
         n: int, None
-            The number of messages (``n`` > 0)  to be printed from the back.
+            The number of fields (``n`` > 0)  to be printed from the back.
         **kwargs: dict, optional
             Other keyword arguments passed to :obj:`ls`.
 
@@ -463,11 +580,11 @@ def tail(self, n=5, **kwargs):
 
         .. code-block:: python
 
-            ds.tail()
-            ds.tail(5)
-            ds.tail(n=5)
-            ds.ls(-5)
-            ds.ls(n=-5)
+            fl.tail()
+            fl.tail(5)
+            fl.tail(n=5)
+            fl.ls(-5)
+            fl.ls(n=-5)
 
         """
         pass
@@ -489,7 +606,7 @@ def unique(
         patch=None,
         cache=True,
         progress_bar=False,
-    ):
+    ) -> dict | tuple:
         """Return the unique values for a given set of metadata keys.
 
         Parameters
@@ -530,58 +647,81 @@ def sel(self, *args, remapping=None, **kwargs) -> "FieldList":
         Parameters
         ----------
         *args: tuple
-            Positional arguments specifying the filter condition as dict.
-            (See below for details).
+            Positional arguments specifying the filter conditions as a dict.
+            Both single or multiple keys are allowed to use. When multiple filter conditions
+            are specified, they are combined with a logical AND operator. Each metadata key in
+            the filter conditions can specify the following type of filter values:
+
+            - single value::
+
+                fl.sel({parameter.variable: "t"})
+
+            - list of values::
+
+                fl.sel({parameter.variable: ["u", "v"]})
+
+            - slice of values (defines a closed interval, so treated as inclusive of both the start
+            and stop values, unlike normal Python indexing). The following example filters the fields
+            with "vertical.level" between 300 and 500 inclusively::
+
+                fl.sel({vertical.level: slice(300, 500)})
+
+            Date and time related keys from the "time" field component are automatically normalised
+            for comparison. This is also applied to the following keys from the raw
+            metadata: "metadata.base_datetime", "metadata.valid_datetime" and "metadata.step_timedelta".
+
+            For example, when filtering by "time.valid_datetime" the following calls are equivalent:
+
+            >>> fl.sel({ "time.valid_datetime": "2018-08-01T12:00:00"})
+            >>> fl.sel({ "time.valid_datetime": "2018080112"})
+            >>> fl.sel({ "time.valid_datetime": 2018080112})
+            >>> fl.sel({ "time.valid_datetime": datetime(2018, 8, 1, 12, 0) })
+
+            Similarly, when filtering by "time.step" the following calls are equivalent (values are assumed
+            to be in hours when the unit is not specified):
+
+            >>> fl.sel({ "time.step": "6h"})
+            >>> fl.sel({ "time.step": 6})
+            >>> fl.sel({ "time.step": "360m"})
+            >>> fl.sel({ "time.step": timedelta(hours=6)})
+
         remapping: dict
-            Creates new metadata keys from existing ones that we can refer to in ``*args`` and
-            ``**kwargs``. E.g. to define a new
-            key "param_level" as the concatenated value of the "param" and "level" keys use::
+            Define new metadata keys from existing ones to use in ``*args`` and ``**kwargs``.
+            E.g. to define a new key "param_level" as the concatenated value of
+            the "parameter.variable" and "vertical.level" keys use::
 
-                remapping={"param_level": "{parameter.variable}{vertical.level}"}
+            >>> remapping={"param_level": "{parameter.variable}{vertical.level}"}
 
             See below for a more elaborate example.
 
         **kwargs: dict, optional
             Other keyword arguments specifying the filter conditions.
-            (See below for details).
 
         Returns
         -------
-        FieldList
-            Returns a new FieldList with the filtered elements. It contains a view to the data in the
-            original object, so no data is copied.
-
-        Notes
-        -----
-        Filter conditions are specified by a set of metadata keys either by a dictionary (in
-        ``*args``) or a set of ``**kwargs``. Both single or multiple keys are allowed to use and each
-        can specify the following type of filter values:
-
-        - single value::
-
-            ds.sel({parameter.variable: "t"})
+        MaskFieldlist, FieldList
+            Returns a MaskFieldList with the reordered fields. It provides a view to the data in the
+            original object, so no data is copied. When called without any arguments it returns the
+            original fieldlist.
 
-        - list of values::
 
-            ds.sel({parameter.variable: ["u", "v"]})
+        Examples
+        --------
+        How-to examples:
 
-        - slice of values (defines a closed interval, so treated as inclusive of both the start
-        and stop values, unlike normal Python indexing)::
+        - :ref:`/how-tos/grib/grib_selection.ipynb`
 
-            # filter levels between 300 and 500 inclusively
-            ds.sel({vertical.level: slice(300, 500)})
+        More examples:
 
-        Examples
-        --------
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/tuv_pl.grib")
-        >>> len(ds)
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "tuv_pl.grib").to_fieldlist()
+        >>> len(fl)
         18
 
         Selecting by a single key ("parameter.variable") with a single value:
 
-        >>> subset = ds.sel({parameter.variable: "t"})
-        >>> for f in subset:
+        >>> fl1 = fl.sel({parameter.variable: "t"})
+        >>> for f in fl1:
         ...     print(f)
         ...
         Field(t,1000,20180801,1200,0,0)
@@ -593,10 +733,10 @@ def sel(self, *args, remapping=None, **kwargs) -> "FieldList":
 
         Selecting by multiple keys ("parameter.variable", "vertical.level") with a list and slice of values:
 
-        >>> subset = ds.sel(
+        >>> fl1 = fl.sel(
         ...     {parameter.variable: ["u", "v"], vertical.level: slice(400, 700)}
         ... )
-        >>> for f in subset:
+        >>> for f in fl1:
         ...     print(f)
         ...
         Field(u,700,20180801,1200,0,0)
@@ -609,11 +749,11 @@ def sel(self, *args, remapping=None, **kwargs) -> "FieldList":
         Using ``remapping`` to specify the selection by a key created from two other keys
         (we created key "param_level" from "parameter.variable" and "vertical.level"):
 
-        >>> subset = ds.sel(
+        >>> fl1 = fl.sel(
         ...     param_level=["t850", "u1000"],
         ...     remapping={"param_level": "{parameter.variable}{vertical.level}"},
         ... )
-        >>> for f in subset:
+        >>> for f in fl1:
         ...     print(f)
         ...
         Field(u,1000,20180801,1200,0,0)
@@ -623,40 +763,54 @@ def sel(self, *args, remapping=None, **kwargs) -> "FieldList":
 
     @abstractmethod
     def order_by(self, *args, remapping=None, patch=None, **kwargs):
-        """Change the order of the elements in a fieldlist.
+        """Change the order of the fields in a fieldlist.
 
         Parameters
         ----------
         *args: tuple
-            Positional arguments specifying the metadata keys to perform the ordering on.
-            (See below for details)
+            Positional arguments specifying the metadata keys to perform the ordering on. Each argument can be
+            a single key (str) or multiple keys as a list/tuple of str or a dictionary.
+            Any metadata keys that :meth:`earthkit.data.core.field.Field.get` accepts can be
+            used here. The order of the keys defines the priority of the ordering. When a dictionary is used it
+            must specify the ordering direction or the order of the values for each key. The ordering direction
+            can be either "ascending" or "descending" (the default is "ascending"). The order of values for
+            a key is defined by a list of values for that key, which must include all the available values
+            for that key in the fieldlist. See the examples below for more details.
         remapping: dict
-            Defines new metadata keys from existing ones that we can refer to in ``*args`` and
+            Define new metadata keys from existing ones to use in ``*args`` and
             ``**kwargs``. E.g. to define a new
-            key "param_level" as the concatenated value of the "param" and "level" keys use::
+            key "param_level" as the concatenated value of the "parameter.variable"
+            and "vertical.level" keys use::
 
-                remapping={"param_level": "{param}{level}"}
+                remapping={"param_level": "{parameter.variable}{vertical.level}"}
 
             See below for a more elaborate example.
 
         **kwargs: dict, optional
-            Other keyword arguments specifying the metadata keys to perform the ordering on.
-            (See below for details)
+            Other keyword arguments specifying the metadata keys to perform the ordering on. Used in
+            the same way as a dictionary in ``*args``.
+
 
         Returns
         -------
-        FieldList
-            Returns a new object with reordered elements. It contains a view to the data in the
-            original object, so no data is copied.
+        MaskFieldList, FieldList
+            Returns a MaskFieldList with the reordered fields. It provides a view to the data in the
+            original object, so no data is copied. When called without any arguments it returns the
+            original fieldlist.
 
         Examples
         --------
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_order_by.ipynb`
+
+
         Ordering by a single metadata key ("parameter.variable"). The default ordering direction
         is ``ascending``:
 
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/test6.grib")
-        >>> for f in ds.order_by("parameter.variable"):
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test6.grib").to_fieldlist()
+        >>> for f in fl.order_by("parameter.variable"):
         ...     print(f)
         ...
         Field(t,850,20180801,1200,0,0)
@@ -669,7 +823,7 @@ def order_by(self, *args, remapping=None, patch=None, **kwargs):
         Ordering by multiple keys (first by "vertical.level" then by "parameter.variable"). The default ordering
         direction is ``ascending`` for both keys:
 
-        >>> for f in ds.order_by(["vertical.level", "parameter.variable"]):
+        >>> for f in fl.order_by(["vertical.level", "parameter.variable"]):
         ...     print(f)
         ...
         Field(t,850,20180801,1200,0,0)
@@ -681,7 +835,7 @@ def order_by(self, *args, remapping=None, patch=None, **kwargs):
 
         Specifying the ordering direction:
 
-        >>> for f in ds.order_by(
+        >>> for f in fl.order_by(
         ...     {"parameter.variable": "ascending", "vertical.level": "descending"}
         ... ):
         ...     print(f)
@@ -694,7 +848,7 @@ def order_by(self, *args, remapping=None, patch=None, **kwargs):
 
         Using the list of all the values of a key ("parameter.variable") to define the order:
 
-        >>> for f in ds.order_by({"parameter.variable": ["u", "t", "v"]}):
+        >>> for f in fl.order_by({"parameter.variable": ["u", "t", "v"]}):
         ...     print(f)
         Field(u,1000,20180801,1200,0,0)
         Field(u,850,20180801,1200,0,0)
@@ -708,7 +862,7 @@ def order_by(self, *args, remapping=None, patch=None, **kwargs):
 
         >>> ordering = ["t850", "t1000", "u1000", "v850", "v1000", "u850"]
         >>> remapping = {"param_level": "{parameter.variable}{vertical.level}"}
-        >>> for f in ds.order_by({"param_level": ordering}, remapping=remapping):
+        >>> for f in fl.order_by({"param_level": ordering}, remapping=remapping):
         ...     print(f)
         Field(t,850,20180801,1200,0,0)
         Field(t,1000,20180801,1200,0,0)
@@ -720,66 +874,123 @@ def order_by(self, *args, remapping=None, patch=None, **kwargs):
         pass
 
     @abstractmethod
-    def to_fieldlist(self, array_namespace=None, device=None, **kwargs):
-        r"""Convert to a new :class:`FieldList`.
+    def to_fieldlist(self, array_namespace=None, device=None, flatten=False, dtype=None):
+        r"""Change how the values stored in each field in a fieldlist.
+
+        This method converts the data values in each field to an array with a given ``array_namespace``
+        and/or ``device``. The resulting fieldlist is then composed of the converted fields.
+        The field values are extracted using the :py:meth:`earthkit.data.core.field.Field.to_array` method
+        of each field.
+
+        When a field already stores its values as an array with a matching ``array_namespace`` and ``device``, a
+        copy of that array is made and stored in the resulting field. This means that even if called without any
+        arguments, the resulting fieldlist will have its own copy of the data values.
+
+        The primary use of this method is to convert the values in GRIB fields loaded from disk to in-memory
+        arrays. By default, the values in GRIB fields loaded from disk are not stored as arrays in memory, but
+        rather as references to the on-disk data. This allows for efficient access to the data without loading
+        it all into memory at once. However, in some cases it may be desirable to convert these values to
+        in-memory arrays for faster access or for compatibility with other libraries. This method provides a
+        way to do that while preserving the metadata of the fields.
 
         Parameters
         ----------
         array_namespace: str, array_namespace or None
-            The array namespace to be used. **New in version 0.19.0**.
+            The array namespace to be used for the field values in the resulting fieldlist. When it is None,
+            the default array namespace used by the underlying data accessor of the field is used. For GRIB
+            it is "numpy".
         device: str or None
-            The device where the array will be allocated. When it is
-            :obj:`None` the default device is used. **New in version 0.19.0**.
-        **kwargs: dict, optional
-            ``kwargs`` are passed to :obj:`to_array` to
-            extract the field values the resulting object will store.
+            The device where the array will be allocated. When it is :obj:`None` the default device is used.
+        flatten: bool
+            When it is True the values are flattened per field. Otherwise the array will have the
+            field's :obj:`shape` per field.
+        dtype: str, array.dtype or None
+            Typecode or data-type of the array. When it is :obj:`None` the default type used by the underlying
+            data accessor per field is used. For GRIB it is ``float64``.
 
         Returns
         -------
         :class:`SimpleFieldList`
-            - a new fieldlist containing :class`ArrayField` fields
+            New fieldlist formed from the converted fields.
 
         Examples
         --------
-        The following example will convert a fieldlist read from a file into a
-        :class:`SimpleFieldList` storing single precision field values.
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_array_namespace.ipynb`
+
+        The following example will convert a fieldlist read from a GRIB file into a
+        :class:`SimpleFieldList` storing data values as single precision arrays in each field.
 
         >>> import numpy as np
-        >>> import earthkit.data
-        >>> ds = earthkit.data.from_source("file", "docs/how-tos/tuv_pl.grib")
-        >>> ds.path
-        'docs/how-tos/tuv_pl.grib'
-        >>> r = ds.to_fieldlist(array_namespace="numpy", dtype=np.float32)
-        >>> r
-        SimpleFieldList(fields=18)
-        >>> hasattr(r, "path")
-        False
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "tuv_pl.grib").to_fieldlist()
+        >>> r = fl.to_fieldlist(array_namespace="numpy", dtype=np.float32)
         >>> r.to_numpy().dtype
         dtype('float32')
 
         """
         pass
 
-    # @abstractmethod
-    # def to_target(self, target, **kwargs):
-    #     pass
-
     @abstractmethod
     def to_tensor(self, *args, **kwargs):
+        """Convert to a tensor-like structure.
+
+        This method is intended to use internally to support the Xarray engine, which converts fieldlist
+        to a tensor-like structure before converting it to an Xarray Dataset or DataArray.
+        """
         pass
 
     @abstractmethod
     def to_cube(self, *args, **kwargs):
+        """Convert to a cube-like structure.
+
+        This method is intended to support fieldlist usage in the ``anemoi-datasets`` package. Planned to be
+        removed in the future and use :obj:`to_tensor` instead.
+        """
+        pass
+
+    @abstractmethod
+    def batched(self, n):
+        """Iterate through the fieldlist in batches of ``n`` fields.
+
+        Parameters
+        ----------
+        n: int
+            Batch size.
+
+        Returns
+        -------
+        object
+            Returns an iterator yielding batches of ``n`` fields. Each batch is a new fieldlist
+            containing a view to the data in the original object, so no data is copied. The last
+            batch may contain fewer than ``n`` fields.
+
+        """
         pass
 
-    # @abstractmethod
-    # def _default_encoder(self):
-    #     pass
+    @abstractmethod
+    def group_by(self, *keys, sort=True):
+        """Iterate through the fieldlist in groups defined by metadata keys.
+
+        Parameters
+        ----------
+        *keys: tuple
+            Positional arguments specifying the metadata keys to group by.
+            Keys can be a single or multiple str, or a list or tuple of str.
 
-    # @abstractmethod
-    # def _encode(self, encoder, **kwargs):
-    #     """Double dispatch to the encoder"""
-    #     pass
+        sort: bool, optional
+            If ``True`` (default), the fieldlist is sorted by the metadata ``keys`` before grouping.
+
+        Returns
+        -------
+        object
+            Returns an iterator yielding batches of fields grouped by the metadata ``keys``. Each
+            batch is a new fieldlist containing a view to the data in the original object, so no data
+            is copied. It generates a new group every time the value of the ``keys`` change.
+
+        """
+        pass
 
     @abstractmethod
     def _unary_op(self, oper):
diff --git a/src/earthkit/data/core/index.py b/src/earthkit/data/core/index.py
index 2489bf98..eef3f42d 100644
--- a/src/earthkit/data/core/index.py
+++ b/src/earthkit/data/core/index.py
@@ -350,7 +350,7 @@ def sel(self, *args, remapping=None, **kwargs):
         return self.new_mask_index(self, indices)
 
     def order_by(self, *args, remapping=None, patch=None, **kwargs):
-        """Change the order of the elements in a fieldlist object.
+        """Change the order of the elements in a fieldlist.
 
         Parameters
         ----------
diff --git a/src/earthkit/data/indexing/empty.py b/src/earthkit/data/indexing/empty.py
index dd4d4e14..aa782efd 100644
--- a/src/earthkit/data/indexing/empty.py
+++ b/src/earthkit/data/indexing/empty.py
@@ -12,8 +12,9 @@
 
 
 class EmptyFieldList(SimpleFieldListBase):
+    """A FieldList implementation that contains no fields."""
+
     def __init__(self):
-        r"""Initialize a FieldList object."""
         self.__fields = []
 
     @property
diff --git a/src/earthkit/data/indexing/indexed.py b/src/earthkit/data/indexing/indexed.py
index 826bf236..a19a8a20 100644
--- a/src/earthkit/data/indexing/indexed.py
+++ b/src/earthkit/data/indexing/indexed.py
@@ -21,8 +21,343 @@
 from .xarray import XarrayMixIn
 
 
+class IndexForFieldList(Index):
+    """Provide fieldlist specific documentation for the Index interface.
+
+    This is the same class as :py:class:`~earthkit.data.core.index.Index`, but with
+    the docstrings of some of the methods overridden to provide fieldlist
+    specific documentation.
+
+    """
+
+    def unique(
+        self,
+        *args,
+        sort=False,
+        drop_none=True,
+        squeeze=False,
+        unwrap_single=False,
+        remapping=None,
+        patch=None,
+        cache=True,
+        progress_bar=False,
+    ) -> dict | tuple:
+        """Return the unique values for a given set of metadata keys.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments specifying the metadata keys to collect unique values for.
+        sort: bool, optional
+            Whether to sort the collected unique values. Default is False.
+        drop_none: bool, optional
+            Whether to drop None values from the collected unique values. Default is True.
+        squeeze: bool, optional
+            When True only returns the metadata keys that have more than one values. Default is False.
+        unwrap_single: bool, optional
+            When True and only one metadata key is specified, the unique values are returned as a tuple instead
+            of a dict. Default is False.
+        remapping: dict, optional
+            A dictionary for remapping keys or values during collection. Default is None.
+        patch: dict, optional
+            A dictionary for patching key values during collection. Default is None.
+        cache: bool, optional
+            Whether to use an a cache attached to the fieldlist for previously collected unique values.
+            Default is True.
+        progress_bar: bool, optional
+            Whether to display a progress bar during collection. Default is False.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the unique values for the specified metadata keys.
+
+        """
+        return super().unique(
+            *args,
+            sort=sort,
+            drop_none=drop_none,
+            squeeze=squeeze,
+            unwrap_single=unwrap_single,
+            remapping=remapping,
+            patch=patch,
+            cache=cache,
+            progress_bar=progress_bar,
+        )
+
+    def sel(self, *args, remapping=None, **kwargs) -> "FieldList":
+        """Select the fields matching the given metadata conditions.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments specifying the filter conditions as a dict.
+            Both single or multiple keys are allowed to use. When multiple filter conditions
+            are specified, they are combined with a logical AND operator. Each metadata key in
+            the filter conditions can specify the following type of filter values:
+
+            - single value::
+
+                fl.sel({parameter.variable: "t"})
+
+            - list of values::
+
+                fl.sel({parameter.variable: ["u", "v"]})
+
+            - slice of values (defines a closed interval, so treated as inclusive of both the start
+            and stop values, unlike normal Python indexing). The following example filters the fields
+            with "vertical.level" between 300 and 500 inclusively::
+
+                fl.sel({vertical.level: slice(300, 500)})
+
+            Date and time related keys from the "time" field component are automatically normalised
+            for comparison. This is also applied to the following keys from the raw
+            metadata: "metadata.base_datetime", "metadata.valid_datetime" and "metadata.step_timedelta".
+
+            For example, when filtering by "time.valid_datetime" the following calls are equivalent:
+
+            >>> fl.sel({ "time.valid_datetime": "2018-08-01T12:00:00"})
+            >>> fl.sel({ "time.valid_datetime": "2018080112"})
+            >>> fl.sel({ "time.valid_datetime": 2018080112})
+            >>> fl.sel({ "time.valid_datetime": datetime(2018, 8, 1, 12, 0) })
+
+            Similarly, when filtering by "time.step" the following calls are equivalent (values are assumed
+            to be in hours when the unit is not specified):
+
+            >>> fl.sel({ "time.step": "6h"})
+            >>> fl.sel({ "time.step": 6})
+            >>> fl.sel({ "time.step": "360m"})
+            >>> fl.sel({ "time.step": timedelta(hours=6)})
+
+        remapping: dict
+            Define new metadata keys from existing ones to use in ``*args`` and ``**kwargs``.
+            E.g. to define a new key "param_level" as the concatenated value of
+            the "parameter.variable" and "vertical.level" keys use::
+
+            >>> remapping={"param_level": "{parameter.variable}{vertical.level}"}
+
+            See below for a more elaborate example.
+
+        **kwargs: dict, optional
+            Other keyword arguments specifying the filter conditions.
+
+        Returns
+        -------
+        MaskFieldlist, FieldList
+            Returns a MaskFieldList with the reordered fields. It provides a view to the data in the
+            original object, so no data is copied. When called without any arguments it returns the
+            original fieldlist.
+
+
+        Examples
+        --------
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_selection.ipynb`
+
+        More examples:
+
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "tuv_pl.grib").to_fieldlist()
+        >>> len(fl)
+        18
+
+        Selecting by a single key ("parameter.variable") with a single value:
+
+        >>> fl1 = fl.sel({parameter.variable: "t"})
+        >>> for f in fl1:
+        ...     print(f)
+        ...
+        Field(t,1000,20180801,1200,0,0)
+        Field(t,850,20180801,1200,0,0)
+        Field(t,700,20180801,1200,0,0)
+        Field(t,500,20180801,1200,0,0)
+        Field(t,400,20180801,1200,0,0)
+        Field(t,300,20180801,1200,0,0)
+
+        Selecting by multiple keys ("parameter.variable", "vertical.level") with a list and slice of values:
+
+        >>> fl1 = fl.sel(
+        ...     {parameter.variable: ["u", "v"], vertical.level: slice(400, 700)}
+        ... )
+        >>> for f in fl1:
+        ...     print(f)
+        ...
+        Field(u,700,20180801,1200,0,0)
+        Field(v,700,20180801,1200,0,0)
+        Field(u,500,20180801,1200,0,0)
+        Field(v,500,20180801,1200,0,0)
+        Field(u,400,20180801,1200,0,0)
+        Field(v,400,20180801, 1200,0,0)
+
+        Using ``remapping`` to specify the selection by a key created from two other keys
+        (we created key "param_level" from "parameter.variable" and "vertical.level"):
+
+        >>> fl1 = fl.sel(
+        ...     param_level=["t850", "u1000"],
+        ...     remapping={"param_level": "{parameter.variable}{vertical.level}"},
+        ... )
+        >>> for f in fl1:
+        ...     print(f)
+        ...
+        Field(u,1000,20180801,1200,0,0)
+        Field(t,850,20180801,1200,0,0)
+        """
+        return super().sel(*args, remapping=remapping, **kwargs)
+
+    def order_by(self, *args, remapping=None, patch=None, **kwargs):
+        """Change the order of the fields in a fieldlist.
+
+        Parameters
+        ----------
+        *args: tuple
+            Positional arguments specifying the metadata keys to perform the ordering on. Each argument can be
+            a single key (str) or multiple keys as a list/tuple of str or a dictionary.
+            Any metadata keys that :meth:`earthkit.data.core.field.Field.get` accepts can be
+            used here. The order of the keys defines the priority of the ordering. When a dictionary is used it
+            must specify the ordering direction or the order of the values for each key. The ordering direction
+            can be either "ascending" or "descending" (the default is "ascending"). The order of values for
+            a key is defined by a list of values for that key, which must include all the available values
+            for that key in the fieldlist. See the examples below for more details.
+        remapping: dict
+            Define new metadata keys from existing ones to use in ``*args`` and
+            ``**kwargs``. E.g. to define a new
+            key "param_level" as the concatenated value of the "parameter.variable"
+            and "vertical.level" keys use::
+
+                remapping={"param_level": "{parameter.variable}{vertical.level}"}
+
+            See below for a more elaborate example.
+
+        **kwargs: dict, optional
+            Other keyword arguments specifying the metadata keys to perform the ordering on. Used in
+            the same way as a dictionary in ``*args``.
+
+
+        Returns
+        -------
+        MaskFieldList, FieldList
+            Returns a MaskFieldList with the reordered fields. It provides a view to the data in the
+            original object, so no data is copied. When called without any arguments it returns the
+            original fieldlist.
+
+        Examples
+        --------
+        How-to examples:
+
+        - :ref:`/how-tos/grib/grib_order_by.ipynb`
+
+
+        Ordering by a single metadata key ("parameter.variable"). The default ordering direction
+        is ``ascending``:
+
+        >>> import earthkit.data as ekd
+        >>> fl = ekd.from_source("sample", "test6.grib").to_fieldlist()
+        >>> for f in fl.order_by("parameter.variable"):
+        ...     print(f)
+        ...
+        Field(t,850,20180801,1200,0,0)
+        Field(t,1000,20180801,1200,0,0)
+        Field(u,850,20180801,1200,0,0)
+        Field(u,1000,20180801,1200,0,0)
+        Field(v,850,20180801,1200,0,0)
+        Field(v,1000,20180801,1200,0,0)
+
+        Ordering by multiple keys (first by "vertical.level" then by "parameter.variable"). The default ordering
+        direction is ``ascending`` for both keys:
+
+        >>> for f in fl.order_by(["vertical.level", "parameter.variable"]):
+        ...     print(f)
+        ...
+        Field(t,850,20180801,1200,0,0)
+        Field(u,850,20180801,1200,0,0)
+        Field(v,850,20180801,1200,0,0)
+        Field(t,1000,20180801,1200,0,0)
+        Field(u,1000,20180801,1200,0,0)
+        Field(v,1000,20180801,1200,0,0)
+
+        Specifying the ordering direction:
+
+        >>> for f in fl.order_by(
+        ...     {"parameter.variable": "ascending", "vertical.level": "descending"}
+        ... ):
+        ...     print(f)
+        Field(t,1000,20180801,1200,0,0)
+        Field(t,850,20180801,1200,0,0)
+        Field(u,1000,20180801,1200,0,0)
+        Field(u,850,20180801,1200,0,0)
+        Field(v,1000,20180801,1200,0,0)
+        Field(v,850,20180801,1200,0,0)
+
+        Using the list of all the values of a key ("parameter.variable") to define the order:
+
+        >>> for f in fl.order_by({"parameter.variable": ["u", "t", "v"]}):
+        ...     print(f)
+        Field(u,1000,20180801,1200,0,0)
+        Field(u,850,20180801,1200,0,0)
+        Field(t,1000,20180801,1200,0,0)
+        Field(t,850,20180801,1200,0,0)
+        Field(v,1000,20180801,1200,0,0)
+        Field(v,850,20180801,1200,0,0)
+
+        Using ``remapping`` to specify the order by a key created from two other keys
+        (we created key "param_level" from "parameter.variable" and "vertical.level"):
+
+        >>> ordering = ["t850", "t1000", "u1000", "v850", "v1000", "u850"]
+        >>> remapping = {"param_level": "{parameter.variable}{vertical.level}"}
+        >>> for f in fl.order_by({"param_level": ordering}, remapping=remapping):
+        ...     print(f)
+        Field(t,850,20180801,1200,0,0)
+        Field(t,1000,20180801,1200,0,0)
+        Field(u,1000,20180801,1200,0,0)
+        Field(v,850,20180801,1200,0,0)
+        Field(v,1000,20180801,1200,0,0)
+        Field(u,850,20180801,1200,0,0)
+        """
+        return super().order_by(*args, remapping=remapping, patch=patch, **kwargs)
+
+    def batched(self, n):
+        """Iterate through the fieldlist in batches of ``n`` fields.
+
+        Parameters
+        ----------
+        n: int
+            Batch size.
+
+        Returns
+        -------
+        object
+            Returns an iterator yielding batches of ``n`` fields. Each batch is a new fieldlist
+            containing a view to the data in the original object, so no data is copied. The last
+            batch may contain fewer than ``n`` fields.
+        """
+        return super().batched(n)
+
+    def group_by(self, *keys, sort=True):
+        """Iterate through the fieldlist in groups defined by metadata keys.
+
+        Parameters
+        ----------
+        *keys: tuple
+            Positional arguments specifying the metadata keys to group by.
+            Keys can be a single or multiple str, or a list or tuple of str.
+
+        sort: bool, optional
+            If ``True`` (default), the fieldlist is sorted by the metadata ``keys`` before grouping.
+
+        Returns
+        -------
+        object
+            Returns an iterator yielding batches of fields grouped by the metadata ``keys``. Each
+            batch is a new fieldlist containing a view to the data in the original object, so no data
+            is copied. It generates a new group every time the value of the ``keys`` change.
+
+        """
+        return super().group_by(*keys, sort=sort)
+
+
 @wrap_maths
-class IndexFieldListBase(XarrayMixIn, PandasMixIn, Index, FieldList):
+class IndexFieldListBase(XarrayMixIn, PandasMixIn, IndexForFieldList, FieldList):
     @property
     def values(self):
         return self._as_array("values")
@@ -220,19 +555,6 @@ def _proc(n: int, keys: str | list | tuple = None, collections: str | list | tup
                 )
                 yield r
 
-            # if component is not None:
-            #     for i in pos_range:
-            #         f = self[i]
-            #         v = {}
-            #         for ns_val in f._dump_component(component, prefix_keys=True, filter=filter).values():
-            #             v.update(ns_val)
-            #         if keys:
-            #             v.update(f._get_fast(keys, default=default, astype=astype, output=dict))
-            #         yield (v)
-            # else:
-            #     for i in pos_range:
-            #         yield (self[i]._get_fast(keys, default=default, astype=astype, output=dict))
-
         if keys == "default":
             keys = self._default_ls_keys()
 
@@ -267,9 +589,9 @@ def _proc():
 
         return format_describe(_proc(), *args, **kwargs)
 
-    def to_fieldlist(self, array_namespace=None, device=None, **kwargs):
+    def to_fieldlist(self, array_namespace=None, device=None, flatten=False, dtype=None):
         return self.from_fields([
-            f.to_array_field(array_namespace=array_namespace, device=device, **kwargs) for f in self
+            f.to_array_field(array_namespace=array_namespace, device=device, flatten=flatten, dtype=dtype) for f in self
         ])
 
     def to_tensor(self, *args, **kwargs):
diff --git a/src/earthkit/data/indexing/simple.py b/src/earthkit/data/indexing/simple.py
index 42f15894..12fd6063 100644
--- a/src/earthkit/data/indexing/simple.py
+++ b/src/earthkit/data/indexing/simple.py
@@ -9,8 +9,6 @@
 
 from abc import abstractmethod
 
-from earthkit.utils.decorators import thread_safe_cached_property
-
 from earthkit.data.core.field import Field
 from earthkit.data.data.fieldlist import FieldListData
 
@@ -18,6 +16,15 @@
 
 
 class SimpleFieldListBase(IndexFieldListBase):
+    """Base class for a SimpleFieldList implementation containing a list of fields.
+
+    Subclasses must implement the ``_fields`` property that should return a list of fields.
+    The rest of the methods are implemented in terms of this property.
+
+    For a concrete implementation of this class,
+    see :py:class:`~earthkit.data.indexing.simple.SimpleFieldList`.
+    """
+
     @property
     @abstractmethod
     def _fields(self):
@@ -72,8 +79,44 @@ def to_data_object(self):
 
 
 class SimpleFieldList(SimpleFieldListBase):
+    """A simple FieldList implementation containing a list of fields.
+
+    This is a top level earthkit-data object and can be directly imported from ``earthkit.data``.
+
+    It can be created with the top level factory function
+    :py:func:`~earthkit.data.core.fieldlist.create_fieldlist` or by
+    the static method :py:meth:`~earthkit.data.core.fieldlist.FieldList.from_fields` that is
+    available for all :class:`~earthkit.data.core.fieldlist.FieldList` implementations.
+
+    Parameters
+    ----------
+    fields: iterable, :class:`~earthkit.data.core.field.Field`, None
+        Iterable of :class:`~earthkit.data.core.field.Field` objects.
+
+    Examples
+    --------
+    A SimpleFieldList can be created from a list of fields:
+
+    >>> import earthkit.data as ekd
+    >>> fl = ekd.SimpleFieldList(list_of_fields)
+
+    It can also be created by the top level factory function
+    :py:func:`~earthkit.data.core.fieldlist.create_fieldlist`:
+
+    >>> import earthkit.data as ekd
+    >>> fl = ekd.create_fieldlist(list_of_fields)
+
+    or with the :py:meth:`~earthkit.data.core.fieldlist.FieldList.from_fields` static method that
+    is available for all :class:`~earthkit.data.core.fieldlist.FieldList` implementations:
+
+    >>> import earthkit.data as ekd
+    >>> fl = ekd.FieldList.from_fields(list_of_fields)
+    >>> fl = ekd.SimpleFieldList.from_fields(list_of_fields)
+    >>> fl = fl_other.from_fields(list_of_fields)
+
+    """
+
     def __init__(self, fields=None):
-        r"""Initialize a FieldList object."""
         if isinstance(fields, Field):
             fields = [fields]
 
@@ -94,25 +137,3 @@ def __setstate__(self, state: dict):
 
     def __repr__(self):
         return f"SimpleFieldList, {len(self)} fields"
-
-
-class LazySimpleFieldList(SimpleFieldListBase):
-    def __init__(self, reader):
-        self._reader = reader
-
-    @thread_safe_cached_property
-    def _fields(self):
-        fields = [x for x in self._reader]
-        self._reader = None
-        return fields
-
-    def __getstate__(self) -> dict:
-        ret = {}
-        # print("SimpleFieldList Getstate")
-        ret["_fields"] = self._fields
-        return ret
-
-    def __setstate__(self, state: dict):
-        # print("SimpleFieldList Setstate")
-        fields = state.pop("_fields")
-        self.__init__(fields)
diff --git a/src/earthkit/data/indexing/xarray.py b/src/earthkit/data/indexing/xarray.py
index 8cc0d384..ff159ee5 100644
--- a/src/earthkit/data/indexing/xarray.py
+++ b/src/earthkit/data/indexing/xarray.py
@@ -408,7 +408,7 @@ def to_xarray(self, engine="earthkit", xarray_open_dataset_kwargs=None, **kwargs
         ... )
 
         """
-        engines = {"earthkit": self.to_xarray_earthkit, "cfgrib": self.to_xarray_cfgrib}
+        engines = {"earthkit": self._to_xarray_earthkit, "cfgrib": self._to_xarray_cfgrib}
         if engine not in engines:
             raise ValueError(f"Unsupported engine: {engine}. Please use one of {list(engines.keys())}")
 
@@ -431,7 +431,7 @@ def to_xarray(self, engine="earthkit", xarray_open_dataset_kwargs=None, **kwargs
 
         return engines[engine](user_xarray_open_dataset_kwargs)
 
-    def to_xarray_earthkit(self, user_kwargs):
+    def _to_xarray_earthkit(self, user_kwargs):
         xarray_open_dataset_kwargs = {}
 
         for key in ["backend_kwargs"]:
@@ -472,7 +472,7 @@ def to_xarray_earthkit(self, user_kwargs):
 
         return from_earthkit(self, backend_kwargs=backend_kwargs, other_kwargs=other_kwargs)
 
-    def to_xarray_cfgrib(self, user_kwargs):
+    def _to_xarray_cfgrib(self, user_kwargs):
         from earthkit.data.readers.grib.xarray import to_xarray_cfgrib
 
         return to_xarray_cfgrib(self, user_kwargs)
diff --git a/src/earthkit/data/readers/__init__.py b/src/earthkit/data/readers/__init__.py
index 02a99844..1f6f4982 100644
--- a/src/earthkit/data/readers/__init__.py
+++ b/src/earthkit/data/readers/__init__.py
@@ -63,8 +63,8 @@ def appendable(self):
     def binary(self):
         return self._binary
 
-    def cache_file(self, *args, **kwargs):
-        return self.source.cache_file(*args, **kwargs)
+    def _cache_file(self, *args, **kwargs):
+        return self.source._cache_file(*args, **kwargs)
 
     def to_target(self, target, *args, **kwargs):
         from earthkit.data.targets import to_target
diff --git a/src/earthkit/data/readers/archive.py b/src/earthkit/data/readers/archive.py
index 6345b66f..5e5f9667 100644
--- a/src/earthkit/data/readers/archive.py
+++ b/src/earthkit/data/readers/archive.py
@@ -73,7 +73,7 @@ def unpack(target, args):
             fsize = 0
             mtime = 0
 
-        self.path = self.cache_file(
+        self.path = self._cache_file(
             unpack,
             [self.path, fsize, mtime],
             extension=".d",
diff --git a/src/earthkit/data/sources/__init__.py b/src/earthkit/data/sources/__init__.py
index 40888749..0feaacff 100644
--- a/src/earthkit/data/sources/__init__.py
+++ b/src/earthkit/data/sources/__init__.py
@@ -22,6 +22,8 @@
 
 
 class Source(Loader):
+    """Base class for all sources."""
+
     name = None
     source_filename = None
 
@@ -29,7 +31,7 @@ def __init__(self, **kwargs):
         self._kwargs = kwargs
         self._parent = None
 
-    def cache_file(self, create, args, **kwargs):
+    def _cache_file(self, create, args, **kwargs):
         owner = self.name
         if owner is None:
             owner = re.sub(r"(?!^)([A-Z]+)", r"-\1", self.__class__.__name__).lower()
@@ -38,6 +40,7 @@ def cache_file(self, create, args, **kwargs):
 
     @property
     def parent(self):
+        """The parent source, if any."""
         if self._parent is None:
             return None
         return self._parent()
@@ -62,6 +65,7 @@ def graph(self, depth=0):
     #     return None
 
     def to_data_object(self):
+        """Convert this source into a data object, if possible."""
         from earthkit.data.data.source import DefaultSourceData
 
         return DefaultSourceData(self)
diff --git a/src/earthkit/data/sources/cds.py b/src/earthkit/data/sources/cds.py
index fccd584c..0954a2d7 100644
--- a/src/earthkit/data/sources/cds.py
+++ b/src/earthkit/data/sources/cds.py
@@ -108,7 +108,7 @@ def retrieve(target, args):
             self.source_filename = cds_result.location.split("/")[-1]
             cds_result.download(target=target)
 
-        return_object = self.cache_file(
+        return_object = self._cache_file(
             retrieve,
             (dataset, request),
             extension=EXTENSIONS.get(request.get("format"), ".cache"),
diff --git a/src/earthkit/data/sources/dummy_source.py b/src/earthkit/data/sources/dummy_source.py
index 1a672b52..d6391c5e 100644
--- a/src/earthkit/data/sources/dummy_source.py
+++ b/src/earthkit/data/sources/dummy_source.py
@@ -231,7 +231,7 @@ def __init__(self, kind, request=None, force=False, extension=None, **kwargs):
         def _generate(target, args):
             return generate(target, **args)
 
-        self.path = self.cache_file(
+        self.path = self._cache_file(
             _generate,
             request,
             hash_extra=kind,
diff --git a/src/earthkit/data/sources/ecfs.py b/src/earthkit/data/sources/ecfs.py
index 253a8afb..ab08cfc6 100644
--- a/src/earthkit/data/sources/ecfs.py
+++ b/src/earthkit/data/sources/ecfs.py
@@ -25,7 +25,7 @@ def __init__(
     ):
         super().__init__(url, **kwargs)
 
-        self.path = self.cache_file(
+        self.path = self._cache_file(
             self._fetch,
             url,
             force=force,
diff --git a/src/earthkit/data/sources/ecmwf_api.py b/src/earthkit/data/sources/ecmwf_api.py
index a76cee2b..266920ab 100644
--- a/src/earthkit/data/sources/ecmwf_api.py
+++ b/src/earthkit/data/sources/ecmwf_api.py
@@ -80,7 +80,7 @@ def _retrieve_one(self, request, *args):
         def retrieve(target, request):
             self.service().execute(request, target)
 
-        return self.cache_file(
+        return self._cache_file(
             retrieve,
             request,
         )
diff --git a/src/earthkit/data/sources/ecmwf_open_data.py b/src/earthkit/data/sources/ecmwf_open_data.py
index 1b59c073..3b85419b 100644
--- a/src/earthkit/data/sources/ecmwf_open_data.py
+++ b/src/earthkit/data/sources/ecmwf_open_data.py
@@ -44,7 +44,7 @@ def _retrieve_one(self, request, *args):
         def retrieve(target, request):
             self.client.retrieve(request, target)
 
-        return self.cache_file(
+        return self._cache_file(
             retrieve,
             request,
         )
diff --git a/src/earthkit/data/sources/fdb.py b/src/earthkit/data/sources/fdb.py
index ab622b0d..3d3e7f23 100644
--- a/src/earthkit/data/sources/fdb.py
+++ b/src/earthkit/data/sources/fdb.py
@@ -98,7 +98,7 @@ def retrieve(target, request):
             with open(target, "wb") as o, self.fdb.retrieve(request) as i:
                 shutil.copyfileobj(i, o)
 
-        return self.cache_file(
+        return self._cache_file(
             retrieve,
             request,
         )
diff --git a/src/earthkit/data/sources/polytope.py b/src/earthkit/data/sources/polytope.py
index 80b70684..23d6ecc7 100644
--- a/src/earthkit/data/sources/polytope.py
+++ b/src/earthkit/data/sources/polytope.py
@@ -152,7 +152,7 @@ def retrieve(target, args):
 
             # The cache file path/data is constructed by using the request only. We cannot simply base
             # it on the URL since the URL may change every time we ask for the pointers.
-            return self.cache_file(
+            return self._cache_file(
                 retrieve,
                 (dataset, request),
             )
diff --git a/src/earthkit/data/sources/url.py b/src/earthkit/data/sources/url.py
index a0f7a4a5..62fb9e20 100644
--- a/src/earthkit/data/sources/url.py
+++ b/src/earthkit/data/sources/url.py
@@ -325,7 +325,7 @@ def download(target, _):
             self.downloader.download(target)
             return self.downloader.cache_data()
 
-        self.path = self.cache_file(
+        self.path = self._cache_file(
             download,
             dict(url=self.url, parts=self.url_parts),
             extension=extension,
diff --git a/src/earthkit/data/sources/wekeo.py b/src/earthkit/data/sources/wekeo.py
index 7876f821..0fbb5123 100644
--- a/src/earthkit/data/sources/wekeo.py
+++ b/src/earthkit/data/sources/wekeo.py
@@ -124,7 +124,7 @@ def _retrieve_one(self, request, dataset):
         def retrieve(target, args):
             self.client(self.prompt).retrieve(args[0], args[1], target)
 
-        return self.cache_file(
+        return self._cache_file(
             retrieve,
             (dataset, request),
             extension=EXTENSIONS.get(request.get("format"), ".cache"),
diff --git a/src/earthkit/data/sources/wekeocds.py b/src/earthkit/data/sources/wekeocds.py
index 0493ede7..de8db895 100644
--- a/src/earthkit/data/sources/wekeocds.py
+++ b/src/earthkit/data/sources/wekeocds.py
@@ -68,7 +68,7 @@ def _retrieve_one(self, request, dataset):
         def retrieve(target, args):
             self.client(self.prompt).retrieve(args[0], args[1], target)
 
-        return self.cache_file(
+        return self._cache_file(
             retrieve,
             (dataset, request),
             extension=EXTENSIONS.get(request.get("format"), ".cache"),