PedestrianDynamics / PedestrianDynamics/PedPy

Restructure user guide into focused topic notebooks

Open
#495 0 comments 0 reactions 1 assignee View on GitHub

@schroedtert is already working on this.

Since Oct 28, 2025.

documentation
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:
    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
  • 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.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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.