From 464ab227dc9f114ea8f23726e16632efd9376dea Mon Sep 17 00:00:00 2001 From: jan <152862650+j-haacker@users.noreply.github.com> Date: Wed, 9 Oct 2024 22:56:30 +0200 Subject: [PATCH] chore(docs): add pages Prerequisites Getting started Tutorials Tests --- docs/conf.py | 14 ++++++++++- docs/getting_started.rst | 2 ++ docs/index.rst | 16 ++++++------- docs/prerequisites.rst | 50 ++++++++++++++++++++++++++++++++++++++++ docs/tests.rst | 15 ++++++++++++ docs/tutorials.rst | 9 ++++++++ 6 files changed, 97 insertions(+), 9 deletions(-) create mode 100644 docs/getting_started.rst create mode 100644 docs/prerequisites.rst create mode 100644 docs/tests.rst create mode 100644 docs/tutorials.rst diff --git a/docs/conf.py b/docs/conf.py index a0348ab..a2c1ab9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,9 +35,21 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', - 'sphinx.ext.githubpages' + 'sphinx.ext.githubpages', + 'sphinx.ext.linkcode', + # 'myst_parser' ] +# for extension linkcode to work +def linkcode_resolve(domain, info): + if domain != 'py': + return None + if not info['module']: + return None + filename = info['module'].replace('.', '/') + print(info, filename) + return "https://github.com/j-haacker/cryoswath/blob/main/%s.py" % filename + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..a13831d --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,2 @@ +Getting started +=============== diff --git a/docs/index.rst b/docs/index.rst index 4614e72..1f74aa3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,10 +6,18 @@ Welcome to cryoswath's documentation! ===================================== +Find the associated GitHub repository at https://github.com/j-haacker/cryoswath. +To set up a working/testing environment, follow the steps discribed in :doc:`prerequisites`. +See the quickstart guide in :doc:`Getting started `, if needed. + .. toctree:: :maxdepth: 1 :caption: Contents: + prerequisites + getting_started + tutorials + tests cryoswath.l1b cryoswath.l2 cryoswath.l3 @@ -17,11 +25,3 @@ Welcome to cryoswath's documentation! cryoswath.misc cryoswath.gis cryoswath.test_plots - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/prerequisites.rst b/docs/prerequisites.rst new file mode 100644 index 0000000..b1f391d --- /dev/null +++ b/docs/prerequisites.rst @@ -0,0 +1,50 @@ +Prerequisites +============= + +.. _install: + +Installation +------------ + +To install cryoswath, simply clone the GitHub repository. + +``git clone git@github.com/j-haacker/cryoswath.git`` + +This will setup a directory structure, download the package, and download some small auxiliary files. +Large resource dependency need to be downloaded manually. + +Data dependencies +----------------- + +cryoswath needs a reference elevation model. +Currently, ArcticDEM and REMA of the Polar Geospatial Center, University of Minnesota (https://www.pgc.umn.edu/data/) are supported. +To use other sources, add their paths to :func:`cryoswath.misc.get_dem_reader`, e.g., `lines following 459 (frozen, maybe different from current version) `_. +Deposit them in ``data/auxiliary/DEM`` or change ``dem_path`` in :mod:`cryoswath.misc` to your needs. + +Further, if you would like to take advantage of the basin shapes provided in the Randolph Glacier Inventory, download them as needed. +Make sure to download both products, "G" (glaciers/basins) and "C" (complexes). +cryoswath will give you hints if any data is missing as you go. +Deposit the shape files in ``data/auxiliary/RGI`` or change ``rgi_path`` in :mod:`cryoswath.misc` to your needs. + +Software dependencies +--------------------- + +There is a bunge of packages, listed in the `requirements.txt `_, that are needed or beneficial to run cryoswath. +Note, that the package names are "conda" names; "pip" names my be slightly different. +Unfortunately there is an issue with ESA's L1b data: when those are read, some values are scaled. +However, the operation used by "xarray" requires the scaling factor to be of a different type. +The two easiest work-arounds are to either patch xarray, or to restrict xarrays version to "<2024.3". + +I provide a docker container, including the patched xarray version. +To fire-up docker, run: + +``docker run --detach --interactive --volume :/altimetry_project cryoswath/cryoswath:nightly`` + +Then, connect with your favorite IDE or ``docker exec --interactive sh``. + +For the longer term, you may want to have your own environment. If you using conda, follow the steps below: + +1. ``conda create --name env_name --file /docker/conda_requirements.txt`` +2. ``conda activate env_name`` +3. ``conda install patch`` +4. ``find -name variables.py -path */env_name/*/xarray/coding/* -exec patch {} /docker/custom_xarray.patch \;`` (the patch works for ``xarray=2024.9.0`` which listed in the requirements.txt used above) diff --git a/docs/tests.rst b/docs/tests.rst new file mode 100644 index 0000000..8a7813a --- /dev/null +++ b/docs/tests.rst @@ -0,0 +1,15 @@ +Tests +===== + +In the directory ``tests/reports`` you can find notebooks that are build to evaluate cryoswath. +If you modify the core components of cryoswath, which you are encouraged to do(!), you shoud run the notebooks to verify that your results are resonable. +This test is only a first step. +If you are satisfied, do a broader validation campaign. + +``tests/reports/l1b_swath_start.ipynb`` tests edge cases for finding the start of the swath domain. This is + +``tests/reports/l1b_waveform.ipynb`` shows the estimated surface elevations for a waveform overlayed by the crosssection of the glacier. + +``tests/reports/l2_dem_comparison.ipynb`` compares many elevation estimates to a reference elevation model. + +``tests/reports/l2_tested_data_comparison.ipynb`` compares the elevation estimates against the results of cryoswath's mother implementation that was thoroughly tested. diff --git a/docs/tutorials.rst b/docs/tutorials.rst new file mode 100644 index 0000000..af61f9c --- /dev/null +++ b/docs/tutorials.rst @@ -0,0 +1,9 @@ +Tutorials +========= + +There is a small number of tutorials that will be extended if I find support. +Those are Jupyter notebooks located in ``scripts`` with names starting with "tutorial". + +``scripts/tutorial.ipynb`` will contain a step-by-step guide to retrieve gridded glacier surface elevation trends from raw (L1b) data. + +``scripts/tutorial__poca.ipynb`` shows how the points of closest approach (POCA), that have a special meaning, can be retrieved.