Output

.github/workflows/docs.yml

@@ -0,0 +1,116 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - output  # Change to main after merge
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'mkdocs.yml'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - output  # Change to main after merge
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:  # Allow manual trigger
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  PYTHON_VERSION: "3.11"
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout rompy-xbeach
+        uses: actions/checkout@v4
+
+      - name: Checkout rompy-notebooks
+        uses: actions/checkout@v4
+        with:
+          repository: rom-py/rompy-notebooks
+          ref: xbeach
+          path: rompy-notebooks
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-docs-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-docs-
+
+      - name: Cache MkDocs Material
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/mkdocs
+          key: mkdocs-material-${{ github.run_id }}
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gdal-bin libgdal-dev
+
+      - name: Install package with docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Sync notebooks
+        run: |
+          mkdir -p docs/examples/components docs/examples/data-interfaces
+          # Copy main workflow notebooks
+          cp rompy-notebooks/notebooks/xbeach/*.ipynb docs/examples/ || true
+          cp rompy-notebooks/notebooks/xbeach/*.yml docs/examples/ || true
+          # Copy component tutorials
+          cp rompy-notebooks/notebooks/xbeach/components/*.ipynb docs/examples/components/ || true
+          # Copy data interface tutorials
+          cp rompy-notebooks/notebooks/xbeach/data-interface/*.ipynb docs/examples/data-interfaces/ || true
+          ls -la docs/examples/
+          ls -la docs/examples/components/
+          ls -la docs/examples/data-interfaces/
+
+      - name: Build documentation
+        run: mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  # Deployment job (only on push to output branch - change to main after merge)
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/output'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/testing.yml

@@ -20,15 +20,15 @@ jobs:
       name: Install dependencies
       run: |
         python -m pip install --upgrade pip build
-        pip install .[dev]
+        pip install -e .[dev]
     -
       name: Run tests
       run: pytest -s -v tests
     -
       name: Run linting
       run: |
         pip install ruff
-        ruff check .
+        ruff check src/ tests/
     -
       name: Build package
       run: python -m build

.gitignore

@@ -101,6 +101,10 @@ ENV/
 # mkdocs documentation
 /site
 
+# Synced notebooks (from rompy-notebooks repo)
+docs/examples/*.ipynb
+docs/examples/*.yml
+
 # mypy
 .mypy_cache/
 

docs/api-reference/components.md

@@ -0,0 +1,224 @@
+# Components API
+
+API reference for all rompy-xbeach components.
+
+## Physics
+
+### Physics (Aggregator)
+
+::: rompy_xbeach.components.physics.Physics
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Wave Models
+
+::: rompy_xbeach.components.physics.wavemodel.Stationary
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.Surfbeat
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.Nonh
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Breaker Formulations
+
+::: rompy_xbeach.components.physics.wavemodel.Roelvink1
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.Roelvink2
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.RoelvinkDaly
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.Baldock
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.wavemodel.Janssen
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Friction
+
+::: rompy_xbeach.components.physics.friction.BedFriction
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.friction.Cf
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.friction.Chezy
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.friction.Manning
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.friction.WhiteColebrook
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.friction.WhiteColebrookGrainsize
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Viscosity
+
+::: rompy_xbeach.components.physics.friction.Viscosity
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Vegetation
+
+::: rompy_xbeach.components.physics.vegetation.Vegetation
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Numerics
+
+::: rompy_xbeach.components.physics.numerics.WaveNumerics
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.numerics.FlowNumerics
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Constants
+
+::: rompy_xbeach.components.physics.constants.PhysicalConstants
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.physics.constants.Coriolis
+    options:
+      show_root_heading: true
+      show_source: false
+
+---
+
+## Sediment
+
+### Sediment (Aggregator)
+
+::: rompy_xbeach.components.sediment.Sediment
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Transport
+
+::: rompy_xbeach.components.sediment.transport.SedimentTransport
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.sediment.transport.TransportNumerics
+    options:
+      show_root_heading: true
+      show_source: false
+
+::: rompy_xbeach.components.sediment.transport.Quasi3D
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Morphology
+
+::: rompy_xbeach.components.sediment.morphology.Morphology
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Bed Composition
+
+::: rompy_xbeach.components.sediment.composition.BedComposition
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Groundwater
+
+::: rompy_xbeach.components.sediment.groundwater.GroundwaterFlow
+    options:
+      show_root_heading: true
+      show_source: false
+
+---
+
+## Output
+
+::: rompy_xbeach.components.output.Output
+    options:
+      show_root_heading: true
+      show_source: false
+
+---
+
+## Boundaries
+
+### Flow Boundaries
+
+::: rompy_xbeach.components.boundary.parameters.FlowBoundaryConditions
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Tide Boundaries
+
+::: rompy_xbeach.components.boundary.parameters.TideBoundaryConditions
+    options:
+      show_root_heading: true
+      show_source: false
+
+### Wave Boundaries
+
+For manual wave boundary specification, see [Wave Boundaries Data API](../data.md#wave-boundaries).
+
+---
+
+## Hotstart
+
+::: rompy_xbeach.components.hotstart.Hotstart
+    options:
+      show_root_heading: true
+      show_source: false
+
+---
+
+## MPI
+
+::: rompy_xbeach.components.mpi.Mpi
+    options:
+      show_root_heading: true
+      show_source: false