From 8271e8eeb9dc488e5f6f4de5236d6bc877e7b999 Mon Sep 17 00:00:00 2001
From: Rambaud Pierrick <12rambau@users.noreply.github.com>
Date: Sat, 23 Nov 2024 15:15:12 +0000
Subject: [PATCH] docs: initialize earthengine in jupyter-sphinx cells

---
 geetools/__init__.py  | 18 ++++++++++++++++++
 geetools/ee_number.py |  5 +++--
 geetools/utils.py     | 30 ++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/geetools/__init__.py b/geetools/__init__.py
index 2f14ed2c..a3f24145 100644
--- a/geetools/__init__.py
+++ b/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
 
diff --git a/geetools/ee_number.py b/geetools/ee_number.py
index 00a6fca3..a996dd1c 100644
--- a/geetools/ee_number.py
+++ b/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()
diff --git a/geetools/utils.py b/geetools/utils.py
index dfca9414..4cf5a74e 100644
--- a/geetools/utils.py
+++ b/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