Improve fieldlist and field docs

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:"
    ]
   },
   {

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": ""
     },

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": ""
     },

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

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):