diff --git a/doc/conf.py b/doc/conf.py
index 1415844cea31b72d11f0b4fbf09733dc0660b7ce..5e63c32b167fd2e17f2a0d846179098842110832 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -19,7 +19,7 @@
import os
import sys
sys.path.insert(0, os.path.abspath('..')) # Source code dir relative to this file
-
+from pyicon import __version__
# -- General configuration ------------------------------------------------
@@ -72,9 +72,9 @@ author = u'pyicon team'
# built documents.
#
# The short X.Y version.
-version = u'0.1'
+version = __version__
# The full version, including alpha/beta/rc tags.
-release = u'0.1'
+release = __version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/doc/doc-installation.md b/doc/doc-installation.md
new file mode 100644
index 0000000000000000000000000000000000000000..9406abbaa56b4047d2dd32c51badb215a3f28391
--- /dev/null
+++ b/doc/doc-installation.md
@@ -0,0 +1,90 @@
+## Installation of pyicon
+
+### On Levante
+
+Activate a suitable python environment. E.g.:
+```
+module load python3/2023.01-gcc-11.2.0
+```
+Other supported python environments are: `python3/2022.01-gcc-11.2.0(default)`, `python3/2023.01-gcc-11.2.0`, and `python3/unstable`.
+
+Download `pyicon` via git (preferably in your home directory, otherwise see `here`):
+```
+git clone https://gitlab.dkrz.de/m300602/pyicon.git
+```
+
+Install `pyicon` via:
+```
+cd pyicon
+pip install -e .
+```
+
+### On an arbitrary system
+
+pyicon is developed for python 3.8 or later. Other versions might work as well but are not supported so far.
+Dependencies are listed in `pyicon/requirements.txt`, however, there are currently three python packages
+that cannot easily installed via pip.
+
+Therefore, it is recommended to setup a mamba environment and install:
+```
+mamba create -n pyicon_311 -c conda-forge python=3.11 zarr cartopy dask
+mamba activate pyicon_311
+```
+
+Afterwards you can install pyicon with pip:
+```
+cd pyicon
+pip install -e .
+```
+
+The above instructions will provide a minimum python environment that will be sufficient for most applications.
+However, some more advanced features might require the installation of further python packages.
+For a complete list of python packages that is supposed to cover all aspects can be obtained from the latest
+`pyicon/ci/requirements*.yml` file.
+
+### From pypi
+
+One might also install `pyicon` from pypi by
+```
+pip install pyicon-diagnostics
+```
+
+However, since `pyicon` is under frequent development and new features and bug fixes sometimes take some time
+to be put to pypi it is rather recommended to follow the above instructions with a local installation by
+`pip install -e .`.
+
+### Update pyicon
+
+If `pyicon` was downloaded via git and installed with `pip install -e .`, one can simply update `pyicon` by a
+```
+git pull
+```
+somewhere within the `pyicon` directory.
+
+If `pyicon` was downloaded via pypi, you can update it with:
+```
+pip install pyicon-diagnostics --upgrade
+```
+
+### Verify the installation
+
+You can check, if you can load `pyicon` by:
+```
+python -c "import pyicon"
+```
+Do not execute this command within a directory that is one directory below `pyicon`,
+e.g. if `pyicon` was installed in your home, thus under `~/pyicon`, do not execute this command
+in your home directory.
+
+If there are issues with loading `pyicon`, you might want to set a python path either, in your shell:
+```
+export PYTHONPATH="${HOME}/pyicon:${PYTHONPATH}"
+```
+
+Alternatively, you can also expand the python pass on top of your python script
+or notebook, by adding:
+```
+import sys, os
+sys.path.append(f"{os.path.expanduser('~')}/pyicon")
+import pyicon as pyic
+```
\ No newline at end of file
diff --git a/doc/doc-quickstart.md b/doc/doc-quickstart.md
new file mode 100644
index 0000000000000000000000000000000000000000..358a830b6fd3487dad2b4e387c3d4179cfbf818f
--- /dev/null
+++ b/doc/doc-quickstart.md
@@ -0,0 +1,72 @@
+## Quickstart
+
+Have a look in the `pyicon/quickstart` directory, here are several scripts
+that do different jobs and that are frequently tested.
+You can execute them individually are all at once (note that some scripts
+require example data which is automatically downloaded if you execute
+`pyicon/quickstart/01_download_example_data.sh`).
+
+In the following, the most important steps from the `pyicon/quickstart`
+scripts are repeated.
+
+### Prepare example data
+
+Download example data to an arbitrary directory:
+```
+wget -r -H -N --cut-dirs=3 --include-directories="/v1/" "https://swiftbrowser.dkrz.de/public/dkrz_07387162e5cd4c81b1376bd7c648bb60/pyicon_example_data/?show_all" p
+```
+
+### First glance at icon data
+
+You can use pyicon's command line tools to visualize the data.
+If you installed `pyicon` with `pip`, you should be ables to
+use `pyic_fig`, `pyic_sec`, and `pyic_view` directly from the
+command line.
+
+If this does not work for whatever reason, you can execute them e.g. by
+```
+/path/to/pyicon/scripts/pyic_fig.py -h
+```
+
+To use these tools to plot the data, go to the directory of the example data:
+```
+cd swift.dkrz.de/example_data_r2b4/outdata
+```
+
+Here, you can plot the data via:
+```
+pyic_fig.py nib2501_oce_P1M_3d_22000101.nc to
+```
+
+For more info how to select data and change the plotting appearance, please type:
+```
+pyic_fig.py -h
+```
+
+You can also plot sections and zonal averages via:
+```
+pyic_sec.py nib2501_oce_P1M_3d_22000101.nc to --section=170W
+```
+
+### More analysis with pyicon-core
+
+You can also use pyicon from within a python script or a Jupyter Notebook, just import it by:
+```python
+import pyicon as pyic
+import xarray as xr
+```
+
+Then, load and plot some data:
+```python
+ds = xr.open_dataset('/path/to/example_data/nib2501_oce_P1M_3d_22000101.nc')
+ds.to.isel(time=0, depth=0).pyic.plot()
+```
+
+More plotting examples can be found [here](https://m300602.gitlab-pages.dkrz.de/pyicon/notebooks_nblink/examp_easyms2022.html).
+
+If you want to derive divergences, gradient and curl on the native grid,
+please have a look at
+[this](https://gitlab.dkrz.de/m300602/pyicon/-/blob/master/notebooks/examp_oce_density_and_velocity_gradients.ipynb)
+or
+[that](https://gitlab.dkrz.de/m300602/pyicon/-/blob/master/notebooks/examp_oce_reconstructions.ipynb)
+notebook.
diff --git a/doc/pyicon-testing.md b/doc/doc-testing.md
similarity index 100%
rename from doc/pyicon-testing.md
rename to doc/doc-testing.md
diff --git a/doc/index.rst b/doc/index.rst
index 9f47049145c2ea407e914beb0bbecc8cfc3a1e04..49e0c197e55bb4bcac187e771fd07ef252039744 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,13 +19,13 @@ Pyicon is hosted here: `<https://gitlab.dkrz.de/m300602/pyicon/>`_
:maxdepth: 1
:caption: Contents:
- installation
- quickstart
+ doc-installation
+ doc-quickstart
pyicon-core
pyicon-tools
pyicon-quickplots
pyicon-view
- pyicon-testing
+ doc-testing
example_notebooks
api
diff --git a/doc/installation.rst b/doc/installation.rst
deleted file mode 100644
index 2d254df9105eb7df5413cd34d041a611d64f5560..0000000000000000000000000000000000000000
--- a/doc/installation.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-Installation of pyicon
-======================
-
-Meeting requirements on Levante
---------------------------------
-
-Activate a suitable python environment. E.g.::
-
- module load python3/2023.01-gcc-11.2.0
-
-Other supported python environments are: ``python3/2022.01-gcc-11.2.0(default)``, ``python3/2023.01-gcc-11.2.0``, and ``python3/unstable``.
-
-Some requirements are not automatically met by the python environments provided on Levante (e.g. `healpy`). If you recognize that
-a package is missing, please install either from the shell with::
-
- pip install package_name
-
-Or within jupyter notebook with::
-
- %pip install package_name
-
-(If this was succesful you can skip the next section.)
-
-Meeting requirements on an arbitrary system
--------------------------------------------
-
-(If you are working on Levante, you can skip this section and see the section above.)
-
-pyicon is developed for python 3.8 or later. Other versions might work as well but are not supported so far.
-Furthermore, a list of modules needed can be found in ``pyicon/requirements.txt`` and the latest ``pyicon/ci/requirements*.yml`` file. Some key modules are:
-
- * numpy, scipy (calculations)
- * matplotlib, cartopy (plotting)
- * netcdf4, xarray (reading / writing netcdf data)
- * ipython, jupyter (for running python)
- * mpi4py, dask (for parallel computing and distributed memory)
-
-With conda you can generate a suitable python environment with::
-
- conda env create -f pyicon/ci/requirements_py39.yml
-
-Download and installation
-------------------------
-
-Download pyicon (e.g. into your home directory)::
-
- git clone https://gitlab.dkrz.de/m300602/pyicon.git
-
-There are two different options to enable including pyicon:
-
-1. Installation via pip::
-
- cd pyicon
-
- pip install -e ./
-
-2. Add pyicon to you PYTHONPATH variable. Therefore, add to your ``.profile`` file the following line (assuming pyicon is installed into the home directory)::
-
- export PYTHONPATH="${HOME}/pyicon:${PYTHONPATH}"
-
-Check if pyicon is running by executing::
-
- python -c "import pyicon"
-
-Pyicon is loaded successfully once you see the line: "----Pyicon was loaded successfully."
-
diff --git a/doc/quickstart.rst b/doc/quickstart.rst
deleted file mode 100644
index 98400e596cb7f3f9bf99e0b1ff4be034b411bbf0..0000000000000000000000000000000000000000
--- a/doc/quickstart.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-Quickstart
-==========
-
-Prepare example data
---------------------
-
-Download example data to an arbitrary directory::
-
- wget -r -H -N --cut-dirs=3 --include-directories="/v1/" "https://swiftbrowser.dkrz.de/public/dkrz_07387162e5cd4c81b1376bd7c648bb60/pyicon_example_data/?show_all" p
-
-First glance at the data with pyicon-tools
-------------------------------------------
-
-You can use pyicon's command line tools to visualize the data. To do this, we are assuming in the following, that you link `pyic_fig.py` and `pyic_sec.py` to a directory which is in your search path. Otherwise, you need to replace `pyic_fig.py` with `/path/to/pyicon/tools/pyic_fig.py`.
-
-First go to the directory of the example data::
-
- cd swift.dkrz.de/example_data_r2b4/outdata
-
-Plot some data via::
-
- pyic_fig.py nib2501_oce_P1M_3d_22000101.nc to
-
-If you want more info how to select data and change the plotting appearance, please type::
-
- pyic_fig.py -h
-
-You can also plot sections and zonal averages via::
-
- pyic_sec.py nib2501_oce_P1M_3d_22000101.nc to --section=170W
-
-More analysis with pyicon-core
-------------------------------
-
-You can also use pyicon from within a python script or a Jupyter Notebook, just import it by::
-
- import pyicon as pyic
- import xarray as xr
-
-Then, load and plot some data::
-
- ds = xr.open_dataset('/path/to/example_data/nib2501_oce_P1M_3d_22000101.nc')
- ds.to.isel(time=0, depth=0).pyic.plot()
-
-More plotting examples can be found here::
-
- https://m300602.gitlab-pages.dkrz.de/pyicon/notebooks_nblink/examp_easyms2022.html
-
-If you want to derive divergences, gradient and curl on the native grid, please have a look into this notebook::
-
- https://gitlab.dkrz.de/m300602/pyicon/-/blob/master/notebooks/examp_oce_density_and_velocity_gradients.ipynb
- https://gitlab.dkrz.de/m300602/pyicon/-/blob/master/notebooks/examp_oce_reconstructions.ipynb
-