Updates to docstrings and notebooks to improve documentation rendering with sphinx

Author: tennlee

notebooks/data/Basic_Indexing.ipynb

@@ -51,7 +51,7 @@
     "tags": []
    },
    "source": [
-    "# DataIndexes\n",
+    "## DataIndexes\n",
     "One of the base classes of `pyearthtools.data` is the `DataIndex`, which provides a unified interface to accessing data, and common data retrieval techniques.\n",
     "\n",
     "As of the writing of this notebook, the following data sources have been implemented:\n",
@@ -513,7 +513,7 @@
    "id": "75e60268-5ccd-4ef8-87d7-6f1b02139a86",
    "metadata": {},
    "source": [
-    "#### Data Loading\n",
+    "## Data Loading\n",
     "Using the `search` function allows retrieval of the filepaths to each requested variable at a given time.\n",
     "\n",
     "From this, the data can be automatically loaded simply by calling the DataIndex with a date, which provides a couple of useful features, which will be explored in later notebooks. "
@@ -1143,7 +1143,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.7"
+   "version": "3.13.2"
   },
   "vscode": {
    "interpreter": {

notebooks/tutorial/HadISD/1_HadISD_Download.ipynb

@@ -21,7 +21,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "e4fb7b1d",
    "metadata": {},
    "outputs": [],
@@ -231,9 +231,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "pyearthtools",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
-   "name": "pyearthtools"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -245,7 +245,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.5"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

notebooks/tutorial/HadISD/2_HadISD_to_zarr.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "55a84e6e",
    "metadata": {},
    "outputs": [],
@@ -298,9 +298,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "pyearthtools",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
-   "name": "pyearthtools"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -312,7 +312,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.5"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

notebooks/tutorial/HadISD/3_HadISD_XGBoost_Pipeline.ipynb

@@ -14,7 +14,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -241,7 +241,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "pet_tutorial",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -255,9 +255,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.11"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

notebooks/tutorial/HadISD/Data_Config.ipynb

@@ -22,7 +22,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "c0c7c48d",
    "metadata": {},
    "outputs": [],
@@ -104,8 +104,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

notebooks/tutorial/HadISD/HadISD_QC_Exploration.ipynb

@@ -27,12 +27,12 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 16,
    "id": "4a7da841",
    "metadata": {},
    "outputs": [],
    "source": [
-    "%run HadISD_config.ipynb"
+    "# %run HadISD_config.ipynb"
    ]
   },
   {
@@ -226,7 +226,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "pet_tutorial",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -240,7 +240,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.11"
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

notebooks/tutorial/HadISD/Pipeline_Config.ipynb

@@ -2,7 +2,7 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "id": "1abab3c3",
    "metadata": {},
    "outputs": [],
@@ -374,8 +374,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.2"
   }
  },
  "nbformat": 4,

notebooks/tutorial/HadISD_Dataset_Integration.ipynb

@@ -100,44 +100,35 @@ class BaseForecastModel:
     ## Config Folder
     The config folder for a model can use the following conventions to ease in setup
 
-    ```txt
-    `Data/`
-        - Location for all data loaders
-    `Pipeline/`
-        - Location for all pipelines
-    ```
+    `Data/` - Location for all data loaders
+    `Pipeline/` - Location for all pipelines
 
     It is assumed that most data configs will have a pipeline name identically to them for
     loading and preparing the data, however, the following exception applies.
-    If a `Data` config has a `()`, with a str inside, it represents a different data source,
-     but the same pipeline,
-    this is can be useful for setting by different sources of the same data, link for downloading,
-     archived data or experiments.
+    If a `Data` config has a `()`, with a str inside, it represents a different data source, but the same pipeline,
+    this is can be useful for setting by different sources of the same data, link for downloading, archived data or experiments.
 
     Additionally, any data with a `-` represents an ancillary source, i.e. forcings and will not be included
-    in the available data sources.
-    Any text prior to the `-` represents the parent source and any after is it's purpose.
+    in the available data sources. Any text prior to the `-` represents the parent source and any after is it's purpose.
 
     Getting `ancillary_pipeline` will give back a dictionary of ancillary pipelines associated with the chosen source.
 
     When creating a model subclass set `_default_config_path` to the default path.
 
     A user can provide a `config_path` during `__init__` to allow access to user defined configs.
     This allows experiments to be easily run, and will follow the conventions outlined above.
-    i.e. Providing a data config with '()' will use the base pipeline.
+    i.e. Providing a data config with `()` will use the base pipeline.
 
     ### Examples
     Consider the following structure.
 
-    ```txt
-    ├── Data
-    │   ├── ERA5-Forcings.yaml
-    │   ├── ERA5(cds)-Forcings.yaml
-    │   ├── ERA5(cds).yaml
-    │   └── ERA5.yaml
-    └── Pipeline
-        └── ERA5.yaml
-    ```
+    >>> ├── Data
+    >>> │   ├── ERA5-Forcings.yaml
+    >>> │   ├── ERA5(cds)-Forcings.yaml
+    >>> │   ├── ERA5(cds).yaml
+    >>> │   └── ERA5.yaml
+    >>> └── Pipeline
+    >>>     └── ERA5.yaml
 
     A user can request either `ERA5` or `ERA5(cds)` as the data source, these two sources are then loaded and use
     `Pipeline/ERA5.yaml` as it's pipeline.

packages/zoo/src/pyearthtools/zoo/model.py

@@ -51,15 +51,15 @@ class CategorisedObjects:
     Key's must be hashable, just like a dictionary.
 
     Examples:
-    ```python
-    record = CategorisedObjects('Example', category_1 = {'sub_cat': 10})
-    record.category_1
-    ─┬ category_1 ──
-        └──sub_cat
-    ```
+
+        >>> record = CategorisedObjects('Example', category_1 = {'sub_cat': 10})
+        >>> record.category_1
+        >>> ─┬ category_1 ──
+        >>>   └──sub_cat
+
     ## Parsing
-        Overriding `_parse` allows custom classes to be parsed when retrieved.
 
+        Overriding `_parse` allows custom classes to be parsed when retrieved.
         Overriding `_name` allows custom classes names to be retrieved when displaying what is available.
     """
 
@@ -290,16 +290,16 @@ class AvailableModels(CategorisedObjects):
     Categorise with these entry points by seperating layers with `_`.
 
     Examples:
-        ```python
-        # Entrypoints
-        # NESM_modelNAME
-        AvailableModels()
-        ─┬ Available Models ──
-            └─┬ NESM ──
-              └──modelNAME
-        ```
+
+        >>> # Entrypoints
+        >>> # NESM_modelNAME
+        >>> AvailableModels()
+        >>> ─┬ Available Models ──
+        >>>   └─┬ NESM ──
+        >>>      └──modelNAME
+
     Can retrieve model by getting attibute one layer at a time,
-    or by `getattr(self, 'NESM/modelNAME'), or if last name is unique, that name alone.
+    or by `getattr(self, 'NESM/modelNAME')`, or if last name is unique, that name alone.
 
     If `NESM/Model` exists within the AvailableModels, it can be retrieved in the following way,
     ```python
@@ -570,19 +570,16 @@ def get_arguments(function: Callable) -> tuple[dict[str, Any], dict[str, Any]]:
 
 
 class TabCompleter:
-    # From https://gist.github.com/iamatypeofwalrus/5637895
     """
-    A tab completer that can either complete from
-    the filesystem or from a list.
-
-    Partially taken from:
-    http://stackoverflow.com/questions/5637124/tab-completion-in-pythons-raw-input
+    A tab completer that can either complete from the filesystem or from a list.
     """
+    # Partially taken from http://stackoverflow.com/questions/5637124/tab-completion-in-pythons-raw-input
+    # From https://gist.github.com/iamatypeofwalrus/5637895
 
     def path_completer(self, text, state):
         """
         This is the tab completer for systems paths.
-        Only tested on *nix systems
+        Only tested on Linux systems
         """
         _ = readline.get_line_buffer().split()