docs: add information for python on how to plug a plugin and how to freshly load a freva config

docs/source/FAQ.ipynb

@@ -71,15 +71,18 @@
     "conda install -c conda-forge freva\n",
     "```\n",
     "\n",
-    "Afterwards you can use freva in your own environment. \n",
+    "Afterwards you can use freva in your own environment. The only difference to the above approach of using the freva python environment is that you will have to tell freva to use the correct configuration. \n",
     "\n",
-    "The only difference to the above approach of using the freva python environment is that you will have to tell freva to use the correct configuration. \n",
+    "If your conda environment does not [automatically load](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#macos-and-linux) `EVALUATION_SYSTEM_CONFIG_FILE` and `EVALUATION_SYSTEM_CONFIG_DIR`\n",
+    "environment variables, then you will need to:\n",
     "\n",
     "```python\n",
+    "# 1. set the environment variables:\n",
+    "import os\n",
+    "os.environ[\"EVALUATION_SYSTEM_CONFIG_FILE\"]=\"/work/freva/evaluation_system.conf\"\n",
+    "os.environ[\"EVALUATION_SYSTEM_CONFIG_DIR\"]=\"/work/freva\"\n",
+    "# 2. load Freva library:\n",
     "import freva\n",
-    "# In order to use freva we have to tell where to get the configuration\n",
-    "freva.config(\"/path/to/the/freva/config/file.conf\")\n",
-    "# Talk to your admins to get the location of the config file.\n",
     "```\n",
     "\n",
     "Please talk to your admins on where the central freva configuration is located."

docs/source/api/APIRef.rst

@@ -793,7 +793,8 @@ Creating zarr endpoints for streaming data
    endpoints. We constrain the data search by ``key=value`` search pairs.
    The only difference is that we have to authenticate by using an access token.
    You will also have to use a valid access token if you want to access the
-   zarr data via http. Please refer to the :ref:`auth` chapter for more details.
+   zarr data via http. Please refer to the `authentication <https://freva-clint.github.io/freva-nextgen/auth/index.html>`__
+   chapter for more details.
 
    .. sourcecode:: http
 

docs/source/notebooks/index.rst

@@ -2,21 +2,21 @@ Examples
 ========
 
 This chapters contains a collection of examples that demonstrate
-the usage for freva by jupyter notebooks. 
+the usage for freva by jupyter notebooks.
 
-After loading the freva module or installing freva in your own python 
-environment you should create a new 
+After loading the freva module or installing freva in your own python
+environment you should create a new
 `jupyter kernel <https://pypi.org/project/ipykernel/>`_. This kernel should have
 the environment variables needed by freva set automatically. You can do this via
-the following command: 
+the following command:
 
 
 .. code:: console
 
     python -m ipykernel install --user --name my-kernel-name --env EVALUATION_SYSTEM_CONFIG_FILE <path_to_evalfile>
 
-The path to the environment variable is project specific for example 
-`/work/ch1187/clint/nextgems/freva/evaluation_system.conf`
+The path to the environment variable is project specific for example
+``/work/ch1187/clint/nextgems/freva/evaluation_system.conf``
 
 Enjoy!
 

src/evaluation_system/api/plugin.py

@@ -172,6 +172,17 @@ def run_tool(
 
         export EVALUATION_SYSTEM_PLUGINS=/path1,plugin1:/path2,plugin2:/path3,plugin3
 
+    .. note::
+        In python (e.g. jupyter notebook) you will need first to add your plugin(s) as
+        an entry in the ``EVALUATION_SYSTEM_PLUGINS`` environment variable and *then*
+        import the Freva module (not the other way around)::
+
+            import os
+            os.environ["EVALUATION_SYSTEM_PLUGINS"] = "/path1,plugin1:/path2,plugin2:/path3,plugin3"
+
+            import freva
+            freva.get_tools_list()
+
     By telling the system where to find the packages it can find the
     :class:`evaluation_system.api.plugin` implementations. The system just
     loads the packages and get to the classes using the

src/evaluation_system/misc/config.py

@@ -18,6 +18,7 @@
 import appdirs
 import requests
 import toml
+
 from evaluation_system.misc import _ConfigWrapper
 from evaluation_system.misc import logger as log
 from evaluation_system.misc.exceptions import ConfigurationException

src/freva/utils.py

@@ -382,6 +382,22 @@ class config:
         freva.config("/work/freva/evaluation_system.conf")
         files = sorted(freva.databrowser(project="user-1234", experiment="extremes"))
 
+    .. note::
+        You cannot freshly set a configuration via ``freva.config("/work/freva/evaluation_system.conf")``
+        if there was no previous ones. For that you will need to:
+
+        ::
+
+           # 1. Set up the environment variables:
+           import os
+           os.environ["EVALUATION_SYSTEM_CONFIG_FILE"]="/work/freva/evaluation_system.conf"
+           os.environ["EVALUATION_SYSTEM_CONFIG_DIR"]="/work/freva"
+           # 2. load Freva library:
+           import freva
+
+        Then, you can use :py:class:`freva.config` to switch to a new configuration.
+
+
     """
 
     _original_config_env = os.environ.get(