Documentation update

docs/api.rst

@@ -22,6 +22,7 @@ Modules
 
 Pre-made Diagnostic
 -------------------
+
 Most users will use pre-made diagnostics. They are organized into four categories and listed below.
 
 Model2Self

docs/doc_examples/index.rst

@@ -5,11 +5,11 @@
 ####################
 
 This page will be filled with a list of common examples. These examples are
-made as notbooks, and will be rendered as such.
+made as notebooks, and will be rendered as such.
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    workflow_example.ipynb
    making_a_diagnostic.ipynb

docs/getting_started/advanced_install.rst

@@ -3,4 +3,62 @@
 Advanced installation
 =====================
 
-WIP
+Valenspy is a Python package but has some non-python dependencies. Therefore, the easist way to install ValEnsPy is to use conda.
+
+Dependencies
+-------------
+
+ValEnsPy officially supports Python 3.10 and above. 
+Its main dependencies are xarray (>v2025.03.0 for DataTree support) and dask. Additionally, ValEnsPy utilizes the existing ecosystem of xarray based weather and climate packages, including xesmf, xclim, and intake-esm. 
+Therefore, Valenspy has a non-python dependency through xesmf, namely ESMF (esmpy). However, if regridding functionality is not needed, ValEnsPy can be installed and used without ESMF.
+
+Installing with conda
+---------------------
+
+To install with conda ensure that you have either `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__ or `Anaconda <https://docs.continuum.io/free/anaconda/>`__ installed, then run the following command in your terminal:
+
+.. code-block:: shell
+
+    #WIP still needs to be published to conda-forge
+
+This will install ValEnsPy and all its dependencies, including ESMF (esmpy) if it is not already installed in the environment.
+
+.. _install_pip:
+
+Installing with pip
+-------------------
+
+Valenspy can be installed via pip from `PyPI <https://pypi.org/project/ValEnsPy/>`__. 
+
+.. warning::
+    Installing ValEnsPy with pip will not install ESMF (esmpy). If you require regridding functionality, either install esmpy in your environment seperately or use conda to install ValEnsPy.
+
+    .. code-block:: shell
+
+        conda install -c conda-forge esmpy
+
+In your terminal run the following command:
+
+.. code-block:: shell
+
+    pip install ValEnsPy
+
+Installing on Windows
+---------------------
+
+ValEnsPy is not yet fully supported on Windows because the xesmf package (in particular the ESMF dependency) is not supported on Windows.
+If you are using Windows and do not require regridding functionality, you can :ref:`install ValEnsPy using pip <_install_pip>` without installing ESMF (esmpy) separately.
+
+Installation from source
+------------------------
+
+#WIP - link to developer guide/contributing pages
+
+Testing the installation
+------------------------
+
+#WIP
+
+
+
+

docs/getting_started/index.rst

@@ -5,10 +5,15 @@ Getting started
 
 A guide to enable you to start productively using ValEnsPy as efficiently as possible.
 
+.. _install:
+
 Installation
 ------------
 
-Valenspy is a pure python package but it has some non-python dependencies (such as ESMpy). The easiest way to install ValEnsPy is to use the conda package manager. If you prefer using pip ensure that you have the required dependencies installed. For help with the install check out the :ref:`advanced installation <advanced_install>` page.
+ValEnsPy has ESMF as a non-python dependency. Therefore, when installing ValEnsPy with pip, ensure that ESMF (esmpy) is already installed in the environment if you wish to use regridding functionality. 
+
+.. warning::
+    To install ValEnsPy on Windows see the :ref:`advanced installation page <advanced_install>`.
 
 .. grid:: 1 2 2 2
     :gutter: 4
@@ -18,13 +23,14 @@ Valenspy is a pure python package but it has some non-python dependencies (such
         :columns: 12 12 6 6
         :padding: 3
 
-        Using Conda
+        Using Conda (Recommended)
 
         ++++++++++++++++++++++
 
         .. code-block:: bash
 
-            #TODO: Add conda install command for non developers
+            #conda install command for non developers
+            #WIP
 
     .. grid-item-card:: Prefer pip?
         :class-card: install-card
@@ -37,16 +43,14 @@ Valenspy is a pure python package but it has some non-python dependencies (such
 
         .. code-block:: bash
 
-            #Ensure non-python dependencies (ESMpy) are installed, e.g. using conda
-            #conda install -c conda-forge esmpy
             pip install valenspy
 
     .. grid-item-card:: In-depth instructions?
         :class-card: install-card
         :columns: 12
         :padding: 3
 
-        Installing a specific version? Installing from source? Check the advanced
+        Installing on Windows? Installing from source or with pip? Check the advanced
         installation page.
 
         +++
@@ -57,20 +61,22 @@ Valenspy is a pure python package but it has some non-python dependencies (such
             :color: secondary
             :expand:
 
-            Learn more
+            Advanced installation
 
 
 Why ValEnsPy?
 -------------
 
-WIP - 2 sentence description of the package and its purpose.
+By utilizing the exisisting xarray ecosystem, ValEnsPy provides a flexible and powerful framework for working with gridded climate and weather data from data processing to diagnostics and from single model evaluations up to multiple ensemble comparisons.
 
 Still not convinced? Check out the :ref:`Why ValEnsPy <why_ValEnsPy>` page.
 
 What do I need to get started?
 ------------------------------
 
-WIP - 3 sentences about knowledge needed to get started with ValEnsPy (xarray!)
+- A working `installation <advanced_install>`_ of ValEnsPy.
+- A basic understanding of `xarray <https://docs.xarray.dev/en/stable/getting-started-guide/index.html>`_ in particular the newly introduced `DataTree <https://docs.xarray.dev/en/stable/user-guide/data-structures.html#datatree>`_ functionality.
+- A basic understanding of `pandas <https://pandas.pydata.org/docs/getting_started/index.html>`_
 
 Got what it takes? Check out the :ref:`quick overview <quick-overview>` page to learn the key concepts of ValEnsPy or check out the :ref:`examples <examples_index>`.
 

docs/getting_started/quick-overview.rst

@@ -3,4 +3,59 @@
 Quick overview
 ==============
 
-WIP
+Here we illustrate the key concepts used in ValEnsPy. 
+
+Components
+----------
+
+Valenspy consists of three main components:
+
+- **Input**: Gathering raw data, loading it and transforming it to ValEnsPy complaint xarray DataSet or DataTree with a uniform naming convention.
+- **Processing**: User dependent processing steps, e.g. regridding, masking, etc.
+- **Diagnostics**: The computation and visualization of the diagnostics.
+
+The main data structures used in ValEnsPy are xarray DataSets and DataTrees. In particular, the new xarray DataTree structure is used to manage (multiple) ensembles of gridded models and observations.
+The image below illustrates the main components of ValEnsPy and how they interact with each other.
+
+.. image:: /_static/images/valenspy_overview.png
+    :alt: Overview diagram of ValEnsPy
+    :align: center
+    :width: 100%
+
+Input
+^^^^^
+
+The input component is responsible for gathering the raw data, loading it and transforming it to ValEnsPy complaint xarray DataSet or DataTree with uniform naming conventions.
+
+The latter is done by the `InputConvertors` class, which is essentially a dataset specific pre-processing function applied when loading the data. It essentially consists of:
+
+- A dictionary to map the raw data variables to the `CMIP6-CORDEX <https://docs.google.com/spreadsheets/d/1qUauozwXkq7r1g-L4ALMIkCNINIhhCPx/edit?gid=1672965248#gid=1672965248>`_ variable names.
+- If required, a dataset specific function to transform the raw data to the ValEnsPy compliant format.
+
+For standard datasets, ValEnsPy has built in input processors but users can also easily define their own input processors.
+
+Gathering and loading the data is done by the `Manager` class, which creates a catalog of all available datasets and utilizes `intake-esm <https://intake-esm.readthedocs.io/en/latest/>`_ to make that data searchable and loadable.
+
+The creation of the catalog is semi-automatic, i.e. only the base directory and a pattern for the files need to be specified and can be shared with others using the same computing infrastructure. The catalog is then used to search for and load the user required data into xarray DataSets or DataTrees.
+When loading the data, the `Manager` class also applies a set of pre-processing steps to each respective dataset through the aformentioned `InputConvertors`.
+
+Processing
+^^^^^^^^^^
+
+The processing component enables users to apply the required processing steps to the data. These are a combination of simple xarray operations time selection, masking and more complex operations like regridding and calculating indicators.
+Where required ValEnsPy extends existing processing functionality, in particular to support the new xarray DataTree structure.
+
+Diagnostics
+^^^^^^^^^^^
+
+Finally, the diagnostics are used to compute and visualize the results. Each diagnostic represents a diagnsotic function and at least one plot.
+Diagnostics are categorized into 4 groups, each with slightly different scope and functionality:
+
+- **Single model diagnostics (Model2Self)**: Compute and visualize aspects of a single model. e.g: spatial average of a variable.
+- **Single model to reference diagnostics (Model2Ref)**: Compute and visualize aspects of a single model compared to a reference dataset. e.g: is the average spatial bias of a variable.
+- **Multi-model diagnostics (Model2Model)**: These diagnostics compute and visualize aspects of an whole ensemble of models. e.g: The "most extreme" model in the ensemble with respect to some variables.
+- **Multi-model to reference diagnostics (Model2Ref)**: These diagnostics compute and visualize aspects of an whole ensemble of models compared to a reference dataset. e.g: The spread of the bias of the ensemble.
+
+The diagnostics functions are applied on the xarray DataSets or DataTrees resulting in some form of output (pandas DataFrame, xarray DataSet or DataTree, dictionary, etc.) which can be saved or visualized with the diagnostic plot functions.
+
+Within ValEnsPy there are `some prexisting diagnostics <../_api_docs>`_ to explorea and use, but users can also define their own diagnostics.

docs/index.rst

@@ -1,6 +1,6 @@
 :html_theme.sidebar_secondary.remove:
-.. _valenspy:
 
+.. _valenspy:
 
 ValEnsPy
 ============================