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.

doc/doc-installation.md

+## 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

doc/doc-quickstart.md

+## 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.

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
   

doc/installation.rst

-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." 
-

doc/quickstart.rst

-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
-