docs: initialize earthengine in jupyter-sphinx cells (#382)

geetools/__init__.py

@@ -1,6 +1,24 @@
 """A toolbox to use with Google Earth Engine Python API.
 
 The ``geetools`` package extends the Google Earth Engine Python API with pre-processing and processing tools for the most used satellite platforms by adding utility methods for different Earth Engine Objects that are friendly with the Python method chaining using the geetools namespace.
+
+.. jupyter-kernel:: python3
+    :id: reference_kernel
+
+.. jupyter-execute::
+
+    import ee, geetools, os, re, httplib2
+
+    if "EARTHENGINE_SERVICE_ACCOUNT" in os.environ:
+        private_key = os.environ["EARTHENGINE_SERVICE_ACCOUNT"]
+        private_key = private_key[1:-1] if re.compile(r"^'[^']*'$").match(private_key) else private_key
+        ee.Initialize.geetools.from_service_account(private_key)
+
+    elif "EARTHENGINE_PROJECT" in os.environ:
+        ee.Initialize(project=os.environ["EARTHENGINE_PROJECT"], http_transport=httplib2.Http())
+
+    else:
+        raise ValueError("EARTHENGINE_SERVICE_ACCOUNT or EARTHENGINE_PROJECT environment variable is missing")
 """
 import ee
 

geetools/ee_number.py

@@ -24,11 +24,12 @@ def truncate(self, nbDecimals: int | ee.Number = 2) -> ee.Number:
             The truncated number.
 
         Examples:
-            .. code-block:: python
+            .. jupyter-execute::
 
                 import ee, geetools
+                from geetools.utils import initialize_documentation
 
-                ee.Initialize()
+                initialize_documentation()
 
                 n = ee.Number(1.23456).geetools.truncate(3)
                 n.getInfo()

geetools/utils.py

@@ -1,9 +1,12 @@
 """Utils methods for file and asset manipulation in the context of batch processing."""
 from __future__ import annotations
 
+import os
 import re
 from datetime import datetime as dt
 
+import ee
+import httplib2
 import numpy as np
 from anyascii import anyascii
 from matplotlib import pyplot as plt
@@ -234,3 +237,30 @@ def plot_data(
     ax.figure.canvas.draw_idle()
 
     return ax
+
+
+def initialize_documentation():
+    """Initialize Earthe Engine Python API in the context of the Documentation build.
+
+    Warning:
+        This method is only used in the documentation build and should not be used in a production environment.
+        ``geetools`` need to be imported prior to import this function.
+    """
+    # use a saved service account key if available
+    if "EARTHENGINE_SERVICE_ACCOUNT" in os.environ:
+        private_key = os.environ["EARTHENGINE_SERVICE_ACCOUNT"]
+        # small massage of the key to remove the quotes coming from RDT
+        private_key = (
+            private_key[1:-1] if re.compile(r"^'[^']*'$").match(private_key) else private_key
+        )
+        ee.Initialize.geetools.from_service_account(private_key)
+
+    elif "EARTHENGINE_PROJECT" in os.environ:
+        ee.Initialize(project=os.environ["EARTHENGINE_PROJECT"], http_transport=httplib2.Http())
+
+    else:
+        raise ValueError(
+            "EARTHENGINE_SERVICE_ACCOUNT or EARTHENGINE_PROJECT environment variable is missing"
+        )
+
+    pass