add docs

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a3bc22a83fed366b93fb1c3e9dbb11dd
+config: 880689b6b6a958c63327a07fb27cb241
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/getting_started.rst.txt

@@ -0,0 +1,2 @@
+Getting started
+===============

_sources/index.rst.txt

@@ -6,22 +6,23 @@
 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 <getting_started>`, if needed.
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
+   prerequisites
+   getting_started
+   tutorials
+   tests
    cryoswath.l1b
    cryoswath.l2
    cryoswath.l3
    cryoswath.l4
    cryoswath.misc
    cryoswath.gis
    cryoswath.test_plots
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

_sources/prerequisites.rst.txt

@@ -0,0 +1,50 @@
+Prerequisites
+=============
+
+.. _install:
+
+Installation
+------------
+
+To install cryoswath, simply clone the GitHub repository.
+
+``git clone [email protected]/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) <https://github.com/j-haacker/cryoswath/blob/ed0115618c9f695aa647eb2fe5a4efb61f6050e3/cryoswath/misc.py#L459>`_.
+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 <https://github.com/j-haacker/cryoswath/blob/main/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 <base dir>:/altimetry_project cryoswath/cryoswath:nightly``
+
+Then, connect with your favorite IDE or ``docker exec --interactive <container hash> 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 <base dir>/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 {} <base dir>/docker/custom_xarray.patch \;`` (the patch works for ``xarray=2024.9.0`` which listed in the requirements.txt used above)

_sources/tests.rst.txt

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

_sources/tutorials.rst.txt

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

_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

_static/doctools.js

@@ -4,7 +4,7 @@
  *
  * Base JavaScript utilities for all Sphinx HTML documentation.
  *
- * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */

_static/language_data.js

@@ -5,15 +5,15 @@
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
  *
- * :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
 
 var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
 
 
-/* Non-minified version is copied as a separate JS file, is available */
+/* Non-minified version is copied as a separate JS file, if available */
 
 /**
  * Porter Stemmer