Summary
Replace the monolithic user guide notebook with a set of focused, topic-specific notebooks and a landing page that explains the overall workflow — including a flowchart — and links to the fundamental diagram notebooks as an end-to-end showcase.
Background / Context
The current user guide is a single large notebook covering all functionality, making it hard to navigate and maintain. Splitting it into focused notebooks improves discoverability and makes it easier to extend. The fundamental diagram notebooks already exist but are not surfaced in the user guide — adding them provides a concrete example of how the individual methods combine into a real analysis.
Technical Details
- Notebooks should be moved to
docs/source/notebooks/ so Sphinx can reference them directly without relative path workarounds
- The landing page (
docs/source/user_guide/index.rst) should describe the workflow and embed a flowchart
- Proposed notebook structure reflecting the typical analysis workflow:
- Measurement Setup — define geometry and measurement regions
- Load Trajectories — import data from various sources
- Preprocessing — (optional) filter and clean data
- Analysis — compute density, speed, flow, and other metrics
- The fundamental diagram notebooks serve as the end-to-end showcase tying the above steps together
- The old monolithic
user_guide.ipynb should be retired once content is distributed
Acceptance Criteria
Summary
Replace the monolithic user guide notebook with a set of focused, topic-specific notebooks and a landing page that explains the overall workflow — including a flowchart — and links to the fundamental diagram notebooks as an end-to-end showcase.
Background / Context
The current user guide is a single large notebook covering all functionality, making it hard to navigate and maintain. Splitting it into focused notebooks improves discoverability and makes it easier to extend. The fundamental diagram notebooks already exist but are not surfaced in the user guide — adding them provides a concrete example of how the individual methods combine into a real analysis.
Technical Details
docs/source/notebooks/so Sphinx can reference them directly without relative path workaroundsdocs/source/user_guide/index.rst) should describe the workflow and embed a flowchartuser_guide.ipynbshould be retired once content is distributedAcceptance Criteria