chore(docs): add pages

Prerequisites
Getting started
Tutorials
Tests

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

docs/getting_started.rst

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

docs/index.rst

@@ -6,22 +6,22 @@
 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`

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

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.

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.