Development tasks

Traveler uses Poe the Poet to give common development workflows short, consistent commands. Poe is installed with the repository’s development dependencies:

uv sync
uv run poe --help

Use uv run poe from the repository root so the task runs in the locked Traveler environment. If that environment is already activated, the shorter poe command is equivalent.

Available tasks

Task	Command	Purpose
Test	uv run poe test	Run the complete pytest suite, including the documentation notebooks selected by the repository’s pytest configuration.
Build documentation	uv run poe make-docs	Re-read every Sphinx source and rebuild all HTML while reusing cached notebook executions. The result is written to docs/_build/html.
Clean documentation build	uv run poe remake-docs	Remove the complete Sphinx build directory, including the notebook execution cache, and rebuild everything. This re-executes every notebook.
Publish documentation	uv run poe publish-docs	Build the documentation, synchronize it to the main branch of driftlesslabs/tv, commit, and push.
Benchmark	uv run poe benchmark	Prepare outside the measured region, then run all four recommended engines three times using the tuned default workload and chunk sizes.

make-docs is the normal documentation command. It clears stale rendered HTML but retains the local docs/_build/.jupyter_cache, so unchanged notebook executions do not need to run again even though all HTML pages are regenerated. Use remake-docs when you specifically need to test execution from a cold notebook cache, or when a cached result may no longer be valid.

Benchmark setup and options

The benchmark’s ActivitySim environment is intentionally separate from the Traveler environment. Create it once before using the Poe benchmark task:

uv run python benchmarking/mtc_full.py setup-activitysim
uv run poe benchmark

The task runs traveler, traveler-sampled, activitysim, and activitysim-multiprocess, with three repetitions of each. Data download and one-time compilation are performed during an unmeasured preparation pass. See Benchmarking for the complete protocol and guidance for interpreting the results.

Additional command-line options are appended to the benchmark command. For example, this runs a small end-to-end check instead of the full workload:

uv run poe benchmark \
  --households 20 \
  --traveler-chunk-size 20 \
  --traveler-sampled-chunk-size 20 \
  --activitysim-chunk-size 20 \
  --activitysim-processes 10 \
  --repeat 1