Ferrite-FEM / Ferrite-FEM/FerriteViz.jl

Docs: give ferriteviewer a dedicated tutorial page

Open
#152 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Julia
Stars
36
Forks
11
Avg merge
14d 16h
Merged PRs (30d)
1

Description

Follow-up to #150. Two review comments there asked for this, from opposite ends of the docs:

- [on `docs/src/api.md`](https://github.com/Ferrite-FEM/FerriteViz.jl/pull/150#discussion_r3649916202) — *"We could (or should?), in a follow-up PR, add a tutorial for the viewer."*
- [on `docs/src/atopics.md`](https://github.com/Ferrite-FEM/FerriteViz.jl/pull/150#discussion_r3652811227) — *"TODO for later PR: Detailed ferriteviewer documentation. I think this is a feature which is a strong selling point of the package."*

## Where the viewer is documented today

After #150 it lives in two places, neither of which is a tutorial:

- **"Composable viewer"**, a section near the end of the *Recommended Practices* page (`atopics.md`). It explains how `Makie.SpecApi` fits in, the three extension points (`layout`, `Control`s, spec helpers), and shows a two-panel viewer plus a sketch of a custom control. It is written for a reader who has already decided to customise the viewer.
- **"Composable viewer"** in the API reference (`api.md`), a flat `@docs` list of 19 exported names: `ferriteviewer`, `Control`, `ControlResult`, `default_controls`, `default_layout`, `default_pipeline`, the seven controls (`FieldMenu`, `ProcessMenu`, `ColormapMenu`, `WireframeToggle`, `LabelsToggle`, `DeformationToggle`, `TimeSlider`) and the six spec helpers (`panelspec`, `solutionplotspec`, `meshplotspec`, `cellplotspec`, `surfaceplotspec`, `arrowplotspec`).

So a user who just wants to *open* the viewer and click around has no page to land on, and the API list gives no sense of which of those 19 names they would ever need.

## What a dedicated page should cover

Roughly in order of what a newcomer needs:

1. `ferriteviewer(ds)` — what the default window gives you, what each menu and toggle does, and how it relates to the filter pipeline (the process menu vs. applying a filter yourself).
2. `ferriteviewer(ds, u_history)` — stepping a solution history with the time slider; how this differs from `FerriteViz.update!` driven live plotting.
3. Swapping *one* thing at a time, so the extension points are introduced separately rather than all at once:
- a different set of controls (`controls = [...]`),
- a custom `layout`,
- a custom `pipeline`.
4. Writing a `Control`: the `ControlResult` contract, and specifically the distinction between `structural` state (re-diffs the spec) and `dynamic` state (streams through the shared observables). That distinction is the part most likely to be got wrong and it is currently one paragraph.
5. When *not* to use the viewer — a plain `solutionplot` on a pipeline is often enough.

## Notes

- The existing "Composable viewer" material in `atopics.md` is mostly the *reasoning*, which is where it belongs. The new page should be the walkthrough, with the atopics section trimmed to what it explains best (the SpecApi diffing model) and cross-linked, rather than duplicated.
- Worth deciding whether this becomes a third top-level page ("Viewer") or a section of the tutorial. The tutorial is currently structured around the pipeline — recipes, then filters — and the viewer is a natural third act.
- The viewer examples in the docs use WGLMakie so they render in the built pages; anything interactive that only works locally should say so.
- Docs are built with `Documenter`, pages listed in `docs/make.jl`.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.