Merge pull request #12 from umr-lops/docs-update

Docs update

Author: agrouaze

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ repos:
     rev: "1.20.0"
     hooks:
       - id: blacken-docs
-        additional_dependencies: [black==26.*]
+        additional_dependencies: ["black==25.11.0"]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: "v6.0.0"

README.md

@@ -35,6 +35,8 @@ Swell Wave) data with WW3 (WaveWatch III) wave model spectra. The
 co-localization can be performed using different matching strategies depending
 on the scientific use case.
 
+![Example of 1to1 SAR/WW3 colocation](docs/coloc_1to1_llustration.png)
+
 ## Features
 
 - **Multiple matching modes**:

docs/Makefile

@@ -0,0 +1,11 @@
+SPHINXBUILD = sphinx-build
+SOURCEDIR   = .
+BUILDDIR    = _build
+
+.PHONY: html clean
+
+html:
+	$(SPHINXBUILD) -b html $(SOURCEDIR) $(BUILDDIR)/html
+
+clean:
+	rm -rf $(BUILDDIR)

docs/api.rst

@@ -3,16 +3,6 @@
 API Reference
 =============
 
-.. automodule:: topsocnww3sp.l2c_processor
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-.. automodule:: topsocnww3sp.read_s1_osw_tops_data
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 .. _l2c_processor:
 
 l2c_processor module

docs/coloc_1to1_llustration.png

@@ -0,0 +1,38 @@
+.. _colocation_notebook:
+
+Co-location Illustration (Notebook)
+===================================
+
+The co-localization process allows for the alignment of SAR and WW3 data. This page describes how to implement a workflow using a notebook.
+
+Typical Notebook Workflow
+--------------------------
+
+A typical analysis notebook would follow these steps:
+
+1. **Data Loading**: Load an L2C NetCDF file produced by ``procl2c``.
+2. **Visualization**: Plot the SAR footprint and the associated WW3 points.
+3. **Spectral Analysis**: Extract spectral parameters (e.g., significant wave height) from both the OSW product and the WW3 spectra for the same coordinates.
+4. **Validation**: Compare values using scatter plots or time-series analysis.
+
+Example snippet for visualization:
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+    import xarray as xr
+    import cartopy.crs as ccrs
+
+    # Load data
+    ds_sar = xr.open_dataset("product_v0.1.nc", group="SAR_intraburst")
+    ds_ww3 = xr.open_dataset("product_v0.1.nc", group="WW3")
+
+    # Plotting map
+    fig = plt.figure(figsize=(10, 6))
+    ax = plt.axes(projection=ccrs.PlateCarree())
+
+    # The SAR tiles can be plotted as points or polygons
+    ax.scatter(ds_sar.oswLon, ds_sar.oswLat, c="blue", label="SAR Tiles")
+    ax.scatter(ds_ww3.longitude, ds_ww3.latitude, c="red", label="WW3 Spectra")
+    ax.legend()
+    plt.show()

docs/colocation_notebook.rst

@@ -1,13 +1,12 @@
 #!/usr/bin/env python3
 from __future__ import annotations
 
-import importlib.metadata
 from typing import Any
 
 project = "topsocnww3sp"
 copyright = "2026, Antoine Grouazel"
 author = "Antoine Grouazel"
-version = release = importlib.metadata.version("topsocnww3sp")
+version = release = "dev"
 
 extensions = [
     "myst_parser",

docs/conf.py

@@ -5,15 +5,22 @@ TOPSOCNWW3SP Documentation
 
 Welcome to the TOPSOCNWW3SP documentation. This project provides tools for colocalizing SAR and WW3 spectral data.
 
+.. image:: coloc_1to1_llustration.png
+   :alt: Example of 1to1 SAR/WW3 colocation
+   :align: center
+   :width: 80%
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    usage
-   api
    install
-   colocation_notebook
+   api
+   l2c_definition
    l2c_output_usage
+   colocation_notebook
    l2c_processor_strategy
 
 Indices and tables

docs/index.rst

@@ -0,0 +1,42 @@
+.. _install:
+
+Installation
+=============
+
+Installation of ``topsocnww3sp`` can be done via pip from the source repository.
+
+Prerequisites
+-------------
+
+- Python 3.10 or higher
+- A working Python environment (venv, conda, etc.)
+
+Install from Source
+--------------------
+
+
+Clone the repository and install the package:
+
+.. code-block:: bash
+
+    git clone https://github.com/umr-lops/topsocnww3sp.git
+    cd topsocnww3sp
+    pip install .
+
+Optional Dependencies
+---------------------
+
+To enable plotting features, install the optional ``plot`` dependencies:
+
+.. code-block:: bash
+
+    pip install ".[plot]"
+
+Verification
+------------
+
+You can verify the installation by checking the version of the installed package:
+
+.. code-block:: bash
+
+    python -c "import topsocnww3sp; print(topsocnww3sp.__version__)"

docs/install.rst

@@ -0,0 +1,40 @@
+.. _l2c_definition:
+
+File Naming Convention & L2C Product Definition
+================================================
+
+This section defines the Level-2C (L2C) product generated by ``topsocnww3sp``.
+
+Product Definition
+------------------
+
+The L2C product is a NetCDF file that co-localizes Sentinel-1 Ocean Waves (OSW) data with WaveWatch III (WW3) spectral data. The goal is to provide a dataset where SAR observations and model spectra are aligned in time and space for easier comparison and analysis.
+
+L2C Output Structure
+---------------------
+
+
+The output files use NetCDF groups to separate different types of information:
+
+* **SAR Groups**: Contain the original OSW data (e.g., ``SAR_intraburst``, ``SAR_interburst``).
+* **WW3 Group**: Contains the associated WW3 spectra. The group name depends on the mode:
+    * In ``lasso`` mode, it is simply named ``WW3``.
+    * In other modes, it is often prefixed by the SAR group (e.g., ``WW3_intraburst``).
+* **MATCH_MAP Groups**: (Used in 1to1, unique, and many modes) Contains mapping information such as distances and pointers from SAR tiles to WW3 spectra.
+
+File Naming Convention
+----------------------
+
+The output files are named following this pattern:
+
+``<original_osw_stem>_<product_version>.nc``
+
+Example: ``s1a-iw1-osw-vv-20220107t062429-20220107t062500-041351-04ea80-001_v0.1.nc``
+
+The files are organized in a hierarchical directory structure:
+``<output_dir>/<year>/<month>/<day>/<safe_name>/<filename>.nc``
+
+Metadata
+--------
+
+Every L2C file contains comprehensive global attributes following CF-1.8 conventions, including the processor version, source SAR product, and the co-localization mode used.