From 4c9c40c12e8db649c7d3a6a76071a02ea8547bfb Mon Sep 17 00:00:00 2001
From: Stefaan Lippens <stefaan.lippens@vito.be>
Date: Wed, 30 Mar 2022 22:53:57 +0200
Subject: [PATCH] Issue #264/#187 add basic docs on configuration files

---
 CHANGELOG.md           |  1 +
 docs/auth.rst          | 40 ++++++++++++++++++++++++++++++
 docs/configuration.rst | 55 ++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst         |  1 +
 4 files changed, 97 insertions(+)
 create mode 100644 docs/configuration.rst

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a1bd4581..5e0febf7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#279](https://github.com/Open-EO/openeo-python-client/issues/279))
 - Added `DataCube.resample_cube_temporal` ([#284](https://github.com/Open-EO/openeo-python-client/issues/284))
 - Add `target_dimension` argument to `DataCube.aggregate_spatial` ([#288](https://github.com/Open-EO/openeo-python-client/issues/288))
+- Add basic configuration file system to define a default back-end URL and enable auto-authentication ([#264](https://github.com/Open-EO/openeo-python-client/issues/264), [#187](https://github.com/Open-EO/openeo-python-client/issues/187))
 
 ### Changed
 
diff --git a/docs/auth.rst b/docs/auth.rst
index 09504da3f..d0de70bea 100644
--- a/docs/auth.rst
+++ b/docs/auth.rst
@@ -408,6 +408,9 @@ when authenticating with the Refresh Token Flow like this::
 You can also bootstrap the refresh token file
 as described in :ref:`oidc_auth_get_refresh_token`
 
+
+.. _auth_configuration_files:
+
 Config files and ``openeo-auth`` helper tool
 =============================================
 
@@ -551,6 +554,43 @@ For example::
     Stored refresh token in '/home/john/.local/share/openeo-python-client/refresh-tokens.json'
 
 
+
+.. _default_url_and_auto_auth:
+
+Default openEO back-end URL and auto-authentication
+=====================================================
+
+.. versionadded:: 0.10.0
+
+
+If you often use the same openEO back-end URL and authentication scheme,
+it can be handy to put these in a configuration file as discussed at :ref:`configuration_files`.
+
+.. note::
+    Note that these (INI) configuration files are different from the JSON config files
+    discussed earlier under :ref:`auth_configuration_files`.
+    The latter are for storing authentication related secrets and are mostly
+    managed automatically.
+    The former are not for storing secrets, are usually edited manually,
+    can be placed at various locations and it is ok to store them in version control.
+
+For example, to define a default back-end and automatically use OpenID Connect authentication
+add these configuration options to the :ref:`desired configuration file <configuration_file_locations>`::
+
+    [Connection]
+    default_backend = openeo.cloud
+    auto_authenticate = oidc
+
+Getting an authenticated connection is now as simple as::
+
+    >>> import openeo
+    >>> con = openeo.connect()
+    Loaded openEO client config from openeo-client-config.ini
+    Using default back-end URL 'openeo.cloud' (from config)
+    Doing auto-authentication 'oidc' (from config)
+    Authenticated using refresh token.
+
+
 Troubleshooting tips
 ====================
 
diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 000000000..d0211e3d1
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,55 @@
+
+===============
+Configuration
+===============
+
+.. warning::
+    Configuration files are an experimental feature
+    and some details are subject to change.
+
+.. versionadded:: 0.10.0
+
+
+.. _configuration_files:
+
+Configuration files
+====================
+
+Some functionality of the openEO Python client library can customized
+through a configuration file.
+
+Format
+-------
+
+At the moment, only INI-style configs are supported.
+This is a simple configuration format, easy to maintain
+and it is supported out of the box in Python (without additional libraries).
+
+Example (note the use of sections and support for comments)::
+
+    [General]
+    # Print loaded configuration file and default back-end URLs in interactive mode
+    verbose = auto
+
+    [Connection]
+    default_backend = openeo.cloud
+
+
+.. _configuration_file_locations:
+
+Location
+---------
+
+The following configuration locations are probed (in this order) for an existing configuration file. The first successful hit will be loaded:
+
+- the path in environment variable ``OPENEO_CLIENT_CONFIG`` if it is set (filename must end with extension ``.ini``)
+- the file ``openeo-client-config.ini`` in the current working directory
+- the file ``${OPENEO_CONFIG_HOME}/openeo-client-config.ini`` if the environment variable ``OPENEO_CONFIG_HOME`` is set
+- the file ``${XDG_CONFIG_HOME}/openeo-python-client/openeo-client-config.ini`` if environment variable ``XDG_CONFIG_HOME`` is set
+- the file ``.openeo-client-config.ini`` in the home folder of the user
+
+
+Configuration options
+----------------------
+
+TODO
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 3e4247a33..bbc4fc832 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,6 +24,7 @@ OpenEO Python Client
    udf
    datacube_construction
    machine_learning
+   configuration
    cookbook/index
    api
    development