Skip to content

Restructure user guide into focused topic notebooks #495

Description

@schroedtert

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:
    1. Measurement Setup — define geometry and measurement regions
    2. Load Trajectories — import data from various sources
    3. Preprocessing — (optional) filter and clean data
    4. 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

  • User guide landing page exists with a flowchart visualising the analysis workflow
  • User guide is split into the four topic notebooks listed above
  • Each notebook is self-contained and can be followed independently
  • Fundamental diagram notebooks are linked from the user guide as an end-to-end showcase
  • Add explanations to Fundamental diagram notebook
  • Old monolithic user guide notebook is removed
  • ReadTheDocs build renders all notebooks and the landing page correctly

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

Fields

No fields configured for Task.

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions