PedestrianDynamics / PedestrianDynamics/PedPy
Restructure user guide into focused topic notebooks
@schroedtert is already working on this.
Since Oct 28, 2025.
- Dominant language
- Pascal
- Stars
- 35
- Forks
- 18
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 2
Description
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
- A short notebook explaining how to use pandas for merging, saving (What to do with the results? section)
- The fundamental diagram notebooks serve as the end-to-end showcase tying the above steps together
- The old monolithic
user_guide.ipynbshould 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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.