Document/fix the gee authentication issue

docs/topics/gee_authentication.rst

@@ -59,16 +59,19 @@ Done, you have set up a Google developer account
 Setup a cloud project on your developer account
 ============================================================================
 
-You need a cloud project to make use of the Google API's. The API's that are used by
-the toolkit has quite a lot of free credentials, so you do not need to worry about
-paying for these services.
+You need a cloud project to make use of the Google API's. Since the data requests
+by the toolkit are (in most non-commercial applictions) limited, the free credits
+provided by Google are sufficient.
 
 #. Create a cloud project: https://console.cloud.Google.com/projectcreate?pli=1
 
    #. Choose a project name and select No organization. --> hit create
    #. (It can take a few seconds to create your project, in the "Cloud overview" you should see your project appear.)
 
 
+For more information on the non-commercial policy we refer to the `Earth Engine for Noncommercial and Research Use page <https://earthengine.google.com/noncommercial/>`_.
+
+
 
 Enable API's on your project
 =============================================================================
@@ -127,3 +130,32 @@ Test your GEE access
    extract small data quantities from GEE. For larger data transfers, GEE will write
    the data to file on your Google Drive, which will raise an error when you select
    'read-only' scopes.
+
+
+.. warning::
+
+   Depending on how you use the toolkit (notebook, ipython, colab, scripts, ...),
+   it can happen that your credential file, which is used for authentication when
+   using GEE functionality, is invalid. If that is the case, an error that looks
+   like:
+
+   `EEException: Not signed up for Earth Engine or project is not registered. Visit https://developers.google.com/earth-engine/guides/access`
+
+   is thrown.
+
+   To update your credential file (which is saved at `~/.config/earthengine/credentials`),
+   you can use the ``connect_to_gee()`` function and pass additional arguments.
+   Here an exmaple on how to update the credetial files:
+
+   .. code-block:: python
+
+       import metobs_toolkit
+
+       metobs_toolkit.connect_to_gee(force=True, #create new credentials
+                                     auth_mode='notebook', # 'notebook', 'localhost', 'gcloud' (requires gcloud installed) or 'colab' (works only in colab)
+                                     )
+
+
+
+   For more information on Authentication we refer to the
+   `Authentication and Initialization Guide <https://developers.google.com/earth-engine/guides/auth>`_ .

metobs_toolkit/__init__.py

@@ -57,8 +57,9 @@
 from metobs_toolkit.obstype_modeldata import ModelObstype, ModelObstype_Vectorfield
 
 
-# import GUI
+# Special functions that can be directly called by te user
 from metobs_toolkit.data_templates.template_build_prompt import build_template_prompt
+from metobs_toolkit.landcover_functions import connect_to_gee
 
 # =============================================================================
 # Import extenders

metobs_toolkit/landcover_functions.py

@@ -19,11 +19,66 @@
 
 # =============================================================================
 #  Connection functions
-# =============================================================================
+# ============================================================================
+
+
+def connect_to_gee(**kwargs):
+    """
+    Setup authentication for the use of the GEE Python API.
+
+    For a fresh kernel, without stored credentials, a prompt/browser window
+    will appear with further instructions for the authentication.
+
+
+    Parameters
+    ----------
+    **kwargs : Kwargs passed to ee.Authenticate()
+        Kwargs are only used by the user, for resetting the gee connection. See
+        the Note below.
+
+    Returns
+    -------
+    None.
+
+    Note
+    ------
+    Upon calling, this function assumes you have a Google developers account,
+    and a project with the Google Earth Engine API enabled.
+    See the * Using Google Earth Engine * page for more info.
+
+    Note
+    ------
+    During the Authentication, you will be asked if you want a read-only scope.
+    A read-only scope is sufficient when the data is transferred directly to your
+    machine (small data transfers), but will not be sufficient when extracting
+    large amounts of data (typical for extracting Modeldata). This is because
+    modeldata is written directly to your Google Drive, and therefore
+    the read-only scope is insufficient.
+
+    Note
+    ------
+    Due to several reasons, an EEExeption may be thrown. This is
+    likely because of an invalid credential file. To fix this, you
+    can update your credential file, and specify a specific authentication method.
+    We found that the "notebook" authentication method works best for most users.
+
+    Here is an example on how to update the credentials:
+
+    .. code-block:: python
 
+        import metobs_toolkit
+
+        metobs_toolkit.connect_to_gee(force=True, #create new credentials
+                                      auth_mode='notebook', # 'notebook', 'localhost', 'gcloud' (requires gcloud installed) or 'colab' (works only in colab)
+                                      )
+
+    """
+
+    if bool(kwargs):  # kwargs are always passed by user, so reinitialize
+        ee.Authenticate(**kwargs)
+        ee.Initialize()
+        return
 
-def connect_to_gee():
-    """Authenticate to GEE if needed."""
     if not ee.data._credentials:  # check if ee connection is initialized
         ee.Authenticate()
         ee.Initialize()