docs: Restructure usage section into workflow-based pages and TUI imp…#229
docs: Restructure usage section into workflow-based pages and TUI imp…#229
Conversation
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #229 +/- ##
==========================================
- Coverage 73.78% 70.34% -3.44%
==========================================
Files 55 55
Lines 3174 3386 +212
==========================================
+ Hits 2342 2382 +40
- Misses 832 1004 +172 ☔ View full report in Codecov by Sentry. |
There was a problem hiding this comment.
Pull request overview
This PR restructures the documentation “Usage” section into workflow-based pages and updates the Textual TUI to better handle project startup, event gating, and snapshot/tool interactions.
Changes:
- Replaces interface-centric usage docs with workflow-step pages and updates the docs navigation accordingly.
- Updates the TUI to add a Project tab, introduce a no-project startup modal, gate key bindings on event selection, and improve snapshot/tool interactions.
- Updates the lockfile for
optypeandscipy-stubs, and adjusts TUI functional tests for the new tab structure/messaging.
Reviewed changes
Copilot reviewed 20 out of 21 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
zensical.toml |
Updates docs navigation to point at the new workflow-based Usage pages. |
uv.lock |
Bumps locked versions for optype and scipy-stubs. |
tests/functional/test_tui.py |
Updates functional tests for the new 3-tab layout and revised “No data” messaging. |
src/aimbat/_tui/modals.py |
Adds NoProjectModal, ParametersModal, and SnapshotActionMenuModal; updates event switcher columns/options. |
src/aimbat/_tui/app.py |
Implements Project tab, startup no-project flow, event-based binding gating, snapshot preview actions, and refactors suspend handling. |
src/aimbat/_tui/aimbat.tcss |
Adds styling for Project tab and the new modals. |
docs/usage/tui.md |
Removes the old TUI-centric usage page in favour of the workflow docs. |
docs/usage/snapshots.md |
Adds workflow documentation for snapshot creation/inspection/rollback/export across interfaces. |
docs/usage/shell.md |
Removes the old shell-centric usage page in favour of the workflow docs. |
docs/usage/project.md |
Adds workflow documentation for project creation and configuration/path resolution. |
docs/usage/mccc.md |
Adds workflow documentation for MCCC finalisation and its parameters. |
docs/usage/inspection.md |
Adds workflow documentation for initial inspection (event/station seismogram plots, what to look for). |
docs/usage/index.md |
Rewrites the Usage landing page to explain interfaces + shared concepts and updated TUI layout/bindings. |
docs/usage/iccs-stack.md |
Adds workflow documentation explaining ICCS stack/matrix views and how to interpret them. |
docs/usage/gui.md |
Removes the old GUI placeholder page. |
docs/usage/event-selection.md |
Adds workflow documentation for choosing/setting events across interfaces. |
docs/usage/data.md |
Adds workflow documentation for data ingestion (SAC/JSON, validation, deletion semantics). |
docs/usage/cli.md |
Removes the old CLI-centric usage page in favour of the workflow docs. |
docs/usage/api.md |
Updates API page wording to reflect the shared underlying library across interfaces. |
docs/usage/alignment.md |
Adds workflow documentation for ICCS alignment and interactive adjustment. |
CHANGELOG.md |
Notes updated seismogram plotting in the changelog. |
| lat, | ||
| lon, | ||
| elev, | ||
| str(len(station.seismograms)), | ||
| key=str(station.id), |
There was a problem hiding this comment.
len(station.seismograms) will lazily load the full seismogram collection for each station, which can become an N+1 query + high-memory path on larger projects. Consider querying a seismogram count per station (e.g. via an aggregate query) instead of loading the relationship just to count it.
| if not _project_exists(engine): | ||
| self.push_screen(NoProjectModal(), self._on_no_project_modal) | ||
| else: | ||
| self._create_iccs() | ||
| self.refresh_all() | ||
|
|
||
| def _on_no_project_modal(self, create: bool | None) -> None: | ||
| if create: | ||
| create_project(engine) | ||
| self._create_iccs() | ||
| self.refresh_all() | ||
| else: | ||
| self.exit() |
There was a problem hiding this comment.
The new startup flow shows NoProjectModal when no project schema exists, but there’s no functional test covering that behaviour (current fixtures always call create_project(engine)). Add a test that runs the TUI against an engine without initialising the schema and asserts the modal is shown and that choosing “create” initialises the project (and “quit” exits).
| def _preview_snapshot_plot( | ||
| self, snap_id: str, plot_type: str, context: bool, all_seis: bool | ||
| ) -> None: | ||
| try: | ||
| with self._suspend(): | ||
| with Session(engine) as session: | ||
| bound = build_iccs_from_snapshot(session, uuid.UUID(snap_id)) | ||
| if plot_type == "stack": | ||
| plot_stack(bound.iccs, context, all_seis, return_fig=False) | ||
| else: | ||
| plot_matrix_image(bound.iccs, context, all_seis, return_fig=False) | ||
| except Exception as exc: |
There was a problem hiding this comment.
_preview_snapshot_plot() suspends Textual without a label, so the terminal clears but doesn’t show the “close matplotlib window to return” hint that _suspend() can display. Consider passing an explicit label here (e.g. “Preview snapshot stack/image”) so users get the same guidance as other interactive plots.
| Press `p` to open the **Interactive Tools** menu, then choose from: | ||
|
|
||
| - **Phase arrival (t1)** — click in the stack to shift all picks globally | ||
| - **Time window** — click to place the window boundaries | ||
| - **Min CC norm** — scroll the matrix image to set the threshold | ||
|
|
||
| Before launching, toggle **Context** (`c`) and **All seismograms** (`a`) | ||
| as needed. The TUI suspends while the matplotlib window is open and | ||
| resumes when you close it. |
There was a problem hiding this comment.
The TUI key binding here is out of date: the Tools menu is now bound to t and p opens Parameters (see AimbatTUI.BINDINGS). Update this section to reference t (and consider renaming “Interactive Tools” to “Tools” for consistency with the UI).
…rovements Replace interface-centric usage pages (cli.md, shell.md, tui.md, gui.md) with workflow-step pages covering the full processing pipeline: project setup, adding data, event selection, initial inspection, ICCS stack, ICCS alignment (including interactive picking), snapshots, and MCCC finalisation. TUI changes: - Gate Align/Tools/Parameters/New Snapshot bindings on event selection rather than active tab - Add NoProjectModal on startup when no project exists (create or quit) - Distinguish "no data" from "no event selected" in the event bar - Fix mypy: NoProjectModal callback accepts bool | None - Update test_event_bar_shows_no_event_message → test_event_bar_shows_no_data_message
…rovements
Replace interface-centric usage pages (cli.md, shell.md, tui.md, gui.md) with workflow-step pages covering the full processing pipeline: project setup, adding data, event selection, initial inspection, ICCS stack, ICCS alignment (including interactive picking), snapshots, and MCCC finalisation.
TUI changes:
📚 Documentation preview 📚: https://aimbat--229.org.readthedocs.build/en/229/