📄 (docs) improve visual layouts (#441)

casenave · web-flow · commit 0c17f81cc816 · 2026-06-06T08:28:43.000+02:00
diff --git a/docs/source/concepts/check.md b/docs/source/concepts/check.md
@@ -55,9 +55,10 @@ Messages are reported with a severity, a stable code, a location and a short
 description.  Errors return exit code `1`; warnings return exit code `2` only in
 strict mode.
 
-## Notes
+## Validation notes
 
-- For CGNS datasets, only `infos.yaml` and `data/` are required at the root.
-- For other backends, metadata files and `constants/` are checked as well.
-- Without `--problem-definition`, all discovered problem definitions are checked.
-- In JSON mode, progress bars are disabled to keep the output parseable.
+!!! note "Dataset validation behavior"
+    - For CGNS datasets, only `infos.yaml` and `data/` are required at the root.
+    - For other backends, metadata files and `constants/` are checked as well.
+    - Without `--problem-definition`, all discovered problem definitions are checked.
+    - In JSON mode, progress bars are disabled to keep the output parseable.
diff --git a/docs/source/concepts/viewer.md b/docs/source/concepts/viewer.md
@@ -154,12 +154,14 @@ The viewer can open data from two places:
 
 When streaming is active, a `streaming` chip appears in the toolbar.
 
-## Tips
-
-- If the 3D view is empty, first select a **Base** in step 4.
-- If the field dropdown is empty, load fields with **Load all** or by selecting
-  features in step 5.
-- If the viewer feels slow on a large dataset, load only one base and a small
-  number of fields.
-- The message at the bottom of the side panel reports the latest action or
-  error.
+
+## Troubleshooting
+
+!!! tip "Viewer tips"
+    - If the 3D view is empty, first select a **Base** in step 4.
+    - If the field dropdown is empty, load fields with **Load all** or by selecting
+      features in step 5.
+    - If the viewer feels slow on a large dataset, load only one base and a small
+      number of fields.
+    - The message at the bottom of the side panel reports the latest action or
+      error.
diff --git a/docs/source/contributing.md b/docs/source/contributing.md
@@ -190,10 +190,10 @@ Before opening a PR that modifies docs or public APIs, run a quick consistency p
 
 1. **Build docs locally**
 
-   ```bash
-   cd docs
-   bash generate_doc.sh
-   ```
+    ```bash
+    cd docs
+    bash generate_doc.sh
+    ```
 
 2. **Validate API references**
 
diff --git a/docs/source/physarena.md b/docs/source/physarena.md
@@ -0,0 +1,14 @@
+# PhysArena
+
+[PhysArena](https://huggingface.co/PhysArena) is a Hugging Face organization page
+dedicated to resources for machine learning on physics simulations.
+
+It provides standardized benchmarks with fixed evaluation protocols, metrics, and splits to enable fair and reproducible comparison of models on physical problems.
+
+All datasets are distributed in the PLAID format, ensuring a uniform, structured representation across benchmarks and seamless interoperability with the PLAID ecosystem.
+
+<p align="center">
+  <a href="https://huggingface.co/PhysArena">
+    <img src="https://huggingface.co/datasets/huggingface/badges/resolve/main/open-in-hf-spaces-sm-dark.svg" alt="Open PhysArena on Hugging Face">
+  </a>
+</p>
diff --git a/docs/source/plaid_benchmarks.md b/docs/source/plaid_benchmarks.md
@@ -61,7 +61,7 @@ As of August 5, 2025
 
 The code to reproduce these results is available in [this repository](https://github.com/PLAID-lib/plaid-benchmarks).
 
-!!! note
+!!! note "Benchmark interpretation notes"
 
     - MMGP does not support variable mesh topologies, which limits its applicability to certain datasets and often necessitates custom preprocessing for new cases. However, when morphing is either unnecessary or inexpensive, it offers a highly efficient solution, combining fast training with good accuracy (e.g., `Tensile2d` and `Rotor37`).
     - MARIO is computationally expensive to train but achieves consistently a very strong performance across most datasets. Its result on `2D_MultiScHypEl` is slightly worse than other tested methods, which may reflect the challenge of capturing complex shape variability in these cases.
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
@@ -14,10 +14,9 @@ To use the library, the simplest way is to install it from the packages availabl
   pip install pyplaid
   ```
 
-**Note**
-
-- Conda-forge packages for all supported operating systems (Linux, macOS, and Windows) and the Linux PyPI package include a bundled pyCGNS dependency. In other situations, which we have not tested, pyCGNS must be installed separately beforehand.
-- On Apple Silicon, users can force an osx-64 conda environment using CONDA_SUBDIR=osx-64, allowing installation of the existing macOS-64 builds under Rosetta.
+!!! note "Installation notes"
+    - Conda-forge packages for all supported operating systems (Linux, macOS, and Windows) and the Linux PyPI package include a bundled pyCGNS dependency. In other situations, which we have not tested, pyCGNS must be installed separately beforehand.
+    - On Apple Silicon, users can force an osx-64 conda environment using CONDA_SUBDIR=osx-64, allowing installation of the existing macOS-64 builds under Rosetta.
 
 
 ## 2. Core concepts
diff --git a/docs/source/tutorials/storage.md b/docs/source/tutorials/storage.md
@@ -356,12 +356,13 @@ sample = converter.to_plaid(
 )
 ```
 
-- `indexers` is a mapping `feature_path -> indexer` (list/array of indices or slice).
-- Indexing is applied on the **last axis** of each indexed feature.
-- This enables a “read less + one gathered output copy” behavior:
-  - **zarr**: partial chunk reads + gathered output
-  - **hf_datasets**: Arrow/NumPy best-effort gather + gathered output
-- **cgns** backend does not use this mechanism.
+!!! info "Indexer behavior"
+    - `indexers` is a mapping `feature_path -> indexer` (list/array of indices or slice).
+    - Indexing is applied on the **last axis** of each indexed feature.
+    - This enables a “read less + one gathered output copy” behavior:
+        - **zarr**: partial chunk reads + gathered output
+        - **hf_datasets**: Arrow/NumPy best-effort gather + gathered output
+    - **cgns** backend does not use this mechanism.
 
 
 ```python
diff --git a/docs/zensical.toml b/docs/zensical.toml
@@ -133,6 +133,7 @@ nav = [
     { "CGNS Standard" = "https://cgns.org/" },
     { "Muscat library" = "https://muscat.readthedocs.io/" },
     { "PLAID Benchmarks" = "plaid_benchmarks.md" },
+    { "PhysArena" = "physarena.md" },
   ] },
 ]
 
@@ -210,6 +211,16 @@ icon = "simple/anaconda"
 link = "https://anaconda.org/conda-forge/plaid"
 name = "plaid on conda-forge"
 
+[[project.extra.social]]
+icon = "simple/arxiv"
+link = "https://arxiv.org/abs/2505.02974"
+name = "PLAID paper on arXiv"
+
+[[project.extra.social]]
+icon = "simple/huggingface"
+link = "https://huggingface.co/PhysArena"
+name = "PhysArena on Hugging Face"
+
 [project.validation]
 # Notebook text outputs contain CGNS tree dumps with square brackets (e.g.
 # ``[1 2 3]``) that are valid rendered content but look like reference-style
