Skip to content

[DOC] Host a clickable dune2 example report suite - #82

Merged
eleanorfrajka merged 1 commit into
mainfrom
docs/demo-report
Aug 18, 2026
Merged

[DOC] Host a clickable dune2 example report suite#82
eleanorfrajka merged 1 commit into
mainfrom
docs/demo-report

Conversation

@eleanorfrajka

Copy link
Copy Markdown
Collaborator

Summary

Publishes a live, self-contained example report suite alongside the docs so readers can explore the real HTML output interactively instead of only reading a description. Fulfils the "worked example report is planned for a future release" note that previously sat at the bottom of reports.rst.

Changes

docs/source/_static/demo/dune2/ (new): the five real dune2_1_2026 report pages — Summary, Stack, Grid, and two per-instrument pages (microcat 2941, aquadopp 9920) — copied from the test fixtures, preserving the instrument/ subdirectory so the header cross-links resolve. Each page is self-contained (all figures base64-embedded; the only external reference is the GitHub link in the footer). Sphinx copies _static/ verbatim, so they publish at .../oceanarray/_static/demo/dune2/….

docs/source/reports.rst: adds a "Live example" section near the top — a click-through thumbnail (opens the Summary page) plus direct links to all five pages — and removes the now-obsolete placeholder note.

docs/Makefile: adds a demo-report target that refreshes the hosted suite from the fixture reports (which the test suite regenerates), so the example can be kept current with one command.

.gitattributes: marks docs/source/_static/demo/** as binary (= -diff -merge -text) on top of the existing linguist-generated, so git treats the demo reports as opaque blobs — no textual diff, no merge, no line-ending normalization — while still tracking them for Sphinx to serve. Golden fixtures keep linguist-generated only (they stay diffable, since their masked images make diffs meaningful on rebaseline).

Notes

The committed snapshot (~2.6 MB across five pages) will drift from the current output when report layout or figures change; make demo-report regenerates it. A future option is to generate it during the docs CI build instead of committing it, but that is deferred.

Breaking changes

None — documentation and build tooling only.

@eleanorfrajka
eleanorfrajka merged commit 6c0eab6 into main Aug 18, 2026
5 checks passed
@eleanorfrajka
eleanorfrajka deleted the docs/demo-report branch August 18, 2026 07:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant