rompy-docs

Shared documentation tooling for rompy and its model plugins (rompy-xbeach, rompy-swan, rompy-schism) and the rompy-notebooks site.

The sites are built separately, one per repository, and read as one resource:

This package holds what they share:

• Build stack: installing rompy-docs installs ProperDocs, Material, mkdocstrings, griffe-pydantic and markdown-exec at compatible versions. Sites build with properdocs build --strict -f mkdocs.yml.
• Theme files: a bar linking all the sites and shared styles, copied into each site by rompy-docs sync.
• Configuration template: template.yml holds the mkdocs.yml blocks every site uses. rompy-docs check reports where a site differs.
• API docs of pydantic models: the template renders fields with griffe-pydantic, including the fields a class inherits from rompy. rompy_docs.griffe:PydanticFieldRules applies pydantic's field rules that griffe-pydantic's static mode misses.
• Notebook links: rompy_docs.notebooks lists notebooks from the inventory the rompy-notebooks site publishes (tutorial tables, example cards, "See it in the notebooks" boxes), so package sites link notebooks without copying them.
• Docstring conversion: rompy-docs convert turns Sphinx .. ipython:: python and .. code-block:: directives into Markdown fences. Converted examples run when the docs are built, with their output shown below the code.

1. Add rompy-docs to the docs extra of the package.

2. Copy the blocks of template.yml into mkdocs.yml, then add the site's own settings, including:

   extra:
     rompy:
       site: xbeach   # rompy, xbeach, swan, schism or notebooks

3. Run rompy-docs sync to copy the theme files into docs/, and commit them.

4. Build with properdocs build --strict -f mkdocs.yml. In CI, also run rompy-docs check. The config keeps the mkdocs.yml name so that other MkDocs-compatible engines, such as Zensical, can read it.

Docstrings may use numpy or google style (the template sets docstring_style: auto). Write examples in the Examples section as markdown-exec fences:

Examples
--------
```python exec="on" source="above" result="text" session="gen3"
from rompy_swan.components.physics import GEN3
print(GEN3().render())
```

The code runs at build time and its printed output appears below it. With --strict, the build fails if an example raises, so the docs build also tests the examples. Use a plain ```python fence for examples that need data files or a model run.