Merge the restructured XBeach notebooks into wp5-1

[rafa-guedes]

This PR merges the restructured XBeach notebooks (now on xbeach) into wp5-1. It keeps all of the wp5-1 site, tooling, SWAN and SCHISM work, and replaces the XBeach part.

What changes for XBeach

• The XBeach tutorial_01–07 lessons and the old components/, data-interface/ and example-* notebooks are replaced by:
  • notebooks/xbeach/tutorial/: 7 ordered lessons, from a first model to a complete storm-impact setup and its YAML/CLI version;
  • notebooks/xbeach/examples/: 17 focused notebooks.
• The notebooks are committed with their outputs, including XBeach runs made with the public Docker image ghcr.io/rom-py/xbeach.
• The data they use is committed in notebooks/xbeach/data/ (2.5 MB), so they run from a clone with no acquisition step.
• notebooks/xbeach/README.md maps every previous notebook to where its content now lives.

We agreed to restructure the SWAN and SCHISM notebooks the same way next, so this layout is written up as the shared target in docs/tutorial-conventions.md.

Fitting into the wp5-1 site

• Metadata: every XBeach notebook has rompy_notebooks metadata. execution_eligible is false for all of them, because their outputs are committed. Five are runtime-dependent: they run XBeach, and those cells are skipped when Docker is not available.
• New example kind for focused, non-sequential notebooks, alongside tutorial and reference.
• Audit: the XBeach checks now use the XBeach lesson template: each notebook opens with What this shows / Prerequisites / You will learn / Data used, and tutorial lessons link to the previous and next lesson. They no longer look for the Learning goals / Checkpoint / Without Rompy markers. The SWAN and SCHISM checks are unchanged.
• Link rewriting: notebooks keep .ipynb links, which work in Jupyter and on GitHub. The MkDocs hook now translates them for the site:
  • notebook links go to their pages, with Jupyter heading anchors converted;
  • images go to their staged copies;
  • a model's README.md goes to its learning tutorial page;
  • data and YAML files go to GitHub.
• Docs pages: xbeach-tutorial.md, models/xbeach.md, the gallery, the coverage matrix and the concept-page links are updated. The home and catalogue pages now link all three learning tutorials.
• Data manifest: data/example-data.json lists the committed XBeach data.

General introduction and concepts (from Tom's review comment)

Tom suggested keeping the high-level explanation of what rompy offers that the SWAN tutorial series gave (data, plugins, file generation). That series will be replaced when SWAN moves to the new layout, so this material now lives in the general, model-agnostic part of the site:

• New "What rompy does" page, the first stop after Home:
  • the chores rompy takes on, and a "without and with rompy" table;
  • the describe → generate → run picture, with a short real example;
  • four key ideas, each linking to its concept page;
  • how the ideas appear in SWAN, XBeach and SCHISM;
  • what stays with the modeller.
• Concepts section: configuration and validation, data, run lifecycle, and plugins, in that order. They keep the existing content and add:
  • the Python/YAML comparison from SWAN tutorial 3, on the configuration page;
  • variants, experiments and chained runs (from SWAN tutorial 7), in the run lifecycle;
  • "See it in the notebooks" links for each model.
• Start here: the home page is now a guide through the site. The installation page covers the notebook environment and model runtimes; "Using the notebooks" covers how the collections are organised, data, stored outputs and using your own data. Documentation tooling is in the Contributing section (renamed from Guides).
• XBeach entry points: the first XBeach tutorial and the XBeach README point new users to "What rompy does".

When SWAN and SCHISM are restructured, their first lessons can point to the same page instead of repeating the concepts.

Fixes to existing wp5-1 code (please check)

• Generated catalogue links: every link in generated/all-notebooks, by-model and by-topic pointed one level too shallow and returned 404 for all models. They now link to the notebook sources, which MkDocs resolves and checks in strict mode.
• Previous/next lesson footer: it rendered as literal markdown text, with paths one level too shallow. It is now HTML and shows lesson titles instead of ids.
• Duplicated role in tutorial-conventions.md: after "rename journeys as tutorials", both roles were called "Tutorial", and kind listed tutorial twice. The focused role is now "Example".
• Duplicate nav entries in mkdocs.yml: index.md (Home and Getting started) and tutorial-conventions.md (Tutorial conventions and Contributor conventions). The duplicates are removed.
• Inventory test: it hard-coded 43 notebooks. It now compares the count with the tracked model notebooks.
• Deploy trigger: docs-pages.yml no longer deploys from wp5-1. Re-add it if you use it for previews before merging to main.

Not changed here, for the SWAN and SCHISM restructure

• These notebook links return 404 on the site:
  • ../../data-concepts/ in SWAN tutorials 01 and 04 and SCHISM tutorials 01 and 04;
  • boundary/boundnest1/ in SWAN tutorial 04;
  • components/output/ in SWAN tutorial 05.
• SWAN and SCHISM notebooks find their data by searching upwards from the working directory for tests/data, which is only filled after the acquisition script has run. The XBeach approach (committed data next to the notebooks, read with paths relative to the notebook) would avoid both the search and the fetch step.
• SWAN example_* notebooks are kind: tutorial with no tutorial number, so the footer hook sorts them into the ordered lesson sequence. They would fit the new example kind.
• requirements.txt lists rompy-xbeach twice (PyPI and git+...@output).
• environment.yml and setup.sh are out of date: Python 3.10, no rompy-swan or rompy-schism, and rompy-xbeach from main. The installation page uses requirements.txt.

Checks

• make docs-build (quality gate plus mkdocs build --strict): passes with no warnings.
• pytest tests: 37 passed, including new tests for the link rewriting.
• Crawled every internal link on the built site: none broken on XBeach pages; the only 404s are the SWAN/SCHISM notebook links listed above.
• The XBeach notebooks were run end to end against rompy-xbeach output before this merge; their outputs are unchanged here.