mamut-routing-publish (MAMUT-routing)¶
The publishing toolkit of the MAMUT-routing repository itself: site payloads and static HTML shell, the build-time caches (ATF sidecars, BKS route geometry), precompression, this documentation, release archives, and the static file server. It runs from a checkout of the repository:
git submodule update --init --recursive MAMUT-routing-lib MAMUT-routing-tools
uv sync
uv run mamut-routing-publish --help
The reference below is generated from the Typer application at build time.
mamut-routing-publish¶
Snapshot, site, and release-archive generation toolkit for the MAMUT-routing benchmark repository.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--version |
boolean | Print the installed mamut-routing-publish version and exit. | None |
--help |
boolean | Show this message and exit. | False |
Subcommands
- release: Generate release .zip archives and the release manifest for MAMUT-routing benchmarks.
- serve: Serve the built static website (dist/ plus repo artifact roots).
- site: Generate site payload JSON files and the static HTML shell of the published website.
mamut-routing-publish release¶
Generate release .zip archives and the release manifest for MAMUT-routing benchmarks.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- build: Generate release .zip archives + manifest.
mamut-routing-publish release build¶
Generate release .zip archives + manifest.
GitHub Releases currently allows up to 1000 assets per release and requires each asset to stay under 2 GiB. This generator warns at 1.5 GiB and fails at 2 GiB or above. See https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--source-repo-dir |
path | Path to the source MAMUT-routing repo root containing the benchmark tree. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--output-dir |
path | Directory where zip archives and the release manifest are written. Defaults to |
None |
--source-commit |
text | Git commit hash to embed in the manifest. Defaults to MAMUT-routing HEAD. | None |
--source-branch |
text | Optional branch name to embed alongside the source commit. | None |
--published-at |
text | Optional publication timestamp in ISO-8601 format. | None |
--snapshot-id |
text | Optional explicit snapshot identifier. | None |
--release-tag |
text | Optional release tag stored in the manifest. | None |
--download-base-url |
text | Optional base URL used to populate manifest download URLs. | None |
--jobs |
integer range (1 and above) |
Number of release archives to compress in parallel. Defaults to auto. | None |
--compresslevel |
integer range (between 0 and 9) |
ZIP deflate compression level. Defaults to high compression for release size. | 9 |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish serve¶
Serve the built static website (dist/ plus repo artifact roots).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--host |
text | Bind address. Use 0.0.0.0 behind a reverse proxy. | 127.0.0.1 |
--port |
integer | Bind port. Defaults to 8082 so a legacy Julia server on 8081 can keep running side by side; deployments pass their proxy target explicitly. | 8082 |
--repo-root |
path | MAMUT-routing repo root to serve. Defaults to $MAMUT_ROUTING_ROOT or the current directory. | None |
--site-dir |
path | Site tree to serve instead of site build --site-output-dir. Relative paths resolve under --repo-root. |
None |
--log-level |
text | uvicorn log level. | info |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site¶
Generate site payload JSON files and the static HTML shell of the published website.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--help |
boolean | Show this message and exit. | False |
Subcommands
- build: Generate site payloads AND the static HTML shell in one step.
- docs: Build the MkDocs documentation (docs/ + mkdocs.yml) into
/docs/. - materialize-atf: Materialize ATF sidecars into dist/atf-cache (git-ignored).
- materialize-route-geometry: Materialize hash-addressed BKS road geometry into dist/.
- payloads: Generate site payload JSON files only.
- precompress: Write .gz + .br sidecars for compressible site files (incremental).
- webapp: Generate the static HTML shell only (assumes payloads already exist).
mamut-routing-publish site build¶
Generate site payloads AND the static HTML shell in one step.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--source-commit |
text | Git commit hash to embed in the snapshot. Defaults to MAMUT-routing HEAD. | None |
--source-branch |
text | Optional branch name to embed alongside the source commit. | None |
--published-at |
text | Optional publication timestamp in ISO-8601 format. | None |
--snapshot-id |
text | Optional explicit snapshot identifier. | None |
--history-summary |
text | Human-readable summary recorded in the history ledger. | Built static site snapshot. |
--atf-max-n |
integer | Materialize ATF sidecars for materialized-td-model instances with at most this many customers before generating payloads (see site materialize-atf). |
400 |
--atf-jobs |
text | Parallel ATF sidecar materialization workers: 'auto' (cores - 2) or an integer >= 1. Each worker holds one full ATF set at a time, so this caps the phase's memory as well as its speed. | auto |
--skip-atf-cache |
boolean | Skip the ATF sidecar cache materialization phase. Instance pages of materialized-td-model families (Lera2026, Poryos2026 TD) then lose their schedule tables and arc-click viewer unless dist/atf-cache is already populated. | False |
--skip-route-geometry |
boolean | Skip BKS route-geometry materialization (route-geometry-cache). Pages whose BKS geometry is not already cached then fall back to straight lines. Staging builds materialize into the staging cache after seeding it from the active dist. | False |
--skip-docs |
boolean | Skip the MkDocs documentation build ( |
False |
--fetch-missing-osm / --no-fetch-missing-osm |
boolean | Automatically fetch and validate missing Poryos2026 source road extracts before route-geometry materialization. | True |
--route-geometry-jobs |
text | Parallel per-city route-geometry workers: 'auto' (1, memory-safe) or an integer >= 1. Each worker can hold a 15+ GiB city road graph. | auto |
--schema-version |
text | Schema version string for the generated site payloads. | 1.0.0 |
--payload-mode |
text | How generated HTML shells should fetch route payloads ('static' or 'api'). | static |
--payload-api-prefix |
text | API prefix embedded into generated HTML shells when --payload-mode is 'api'. | /api/site-payload |
--payload-root-dir |
path | Directory under the site output root for route payload JSON files. | site-payloads |
--site-output-dir |
path | Directory where generated website files are written. Relative paths resolve under --output-repo-dir. | dist |
--state-dir |
path | Persistent publication state dir (history ledger, snapshot inventories). Defaults to |
None |
--precompress |
boolean | Write .gz + .br sidecars for compressible site files after the build, so serve can negotiate precompressed responses. |
False |
--progress-format |
text | Progress output format: auto, text, json, or off. | auto |
--quiet |
boolean | Disable progress and status reporting. | False |
--list-files |
boolean | Include generated file paths in the final JSON summary. | False |
--jobs |
text | Parallel instance-resolution workers: 'auto' or an integer >= 1. | auto |
--basemap-api-key |
text | CARTO basemaps API key written into the workbench page so the map can use the CARTO Positron / Dark Matter vector basemaps. Without it the workbench map falls back to OpenStreetMap tiles. | None |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site docs¶
Build the MkDocs documentation (docs/ + mkdocs.yml) into
The documentation is served by the website under /docs/. site build runs
this as a phase; use this command to rebuild the documentation alone.
Requires the docs toolchain (uv sync --group docs, installed by default).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--site-output-dir |
path | Site tree the documentation is written into (as |
dist |
--strict / --no-strict |
boolean | Fail on any MkDocs warning (missing nav target, broken link, unresolved reference). Strict is what CI and deployments use. | True |
--quiet |
boolean | Silence MkDocs warnings on stderr (errors still abort). | False |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site materialize-atf¶
Materialize ATF sidecars into dist/atf-cache (git-ignored).
Covers materialized-td-model families with no committed sidecar (Lera2026
igp-profile, Poryos2026 TD road-graph) so the arc-click viewer and BKS
schedule tables work. site build runs this phase automatically; this
standalone command exists to pre-warm the cache or use a custom cap.
Incremental: existing cache files are reused; TDVRPTW/TDVRP twins share
one file.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--max-n |
integer | Materialize ATF sidecars only for igp-profile instances with at most this many customers (an n=1000 sidecar weighs ~82 MB gzipped). | 400 |
--jobs |
integer | Parallel materialization workers (default: cores - 2). | None |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site materialize-route-geometry¶
Materialize hash-addressed BKS road geometry into dist/.
The cache is publication-only and incremental by exact BKS bytes. A changed BKS receives a new sidecar; unchanged BKS reuse their existing hash-addressed artifact.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--min-n |
integer | Materialize BKS route geometry for Poryos2026 instances with at least this many customers (default: all sizes). | 1 |
--jobs |
text | Parallel per-city materialization workers: 'auto' (1, memory-safe) or an integer >= 1. | auto |
--fetch-missing-osm / --no-fetch-missing-osm |
boolean | Fetch and validate missing source road extracts from benchmark sidecar bounds before materializing. | False |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site payloads¶
Generate site payload JSON files only.
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--source-commit |
text | Git commit hash to embed in the snapshot. Defaults to MAMUT-routing HEAD. | None |
--source-branch |
text | Optional branch name to embed alongside the source commit. | None |
--published-at |
text | Optional publication timestamp in ISO-8601 format. | None |
--snapshot-id |
text | Optional explicit snapshot identifier. | None |
--history-summary |
text | Human-readable summary recorded in the history ledger. | Generated site payload snapshot. |
--schema-version |
text | Schema version string for the generated site payloads. | 1.0.0 |
--payload-root-dir |
path | Directory (relative to the site output root) where route payload JSON files are written. | site-payloads |
--site-output-dir |
path | Directory where generated website files are written. Relative paths resolve under --output-repo-dir. | dist |
--state-dir |
path | Persistent publication state dir (history ledger, snapshot inventories). Defaults to |
None |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site precompress¶
Write .gz + .br sidecars for compressible site files (incremental).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--site-output-dir |
path | Site tree to precompress. Relative paths resolve under --output-repo-dir. | dist |
--jobs |
integer | Parallel compression workers (default: cores - 2). | None |
--help |
boolean | Show this message and exit. | False |
mamut-routing-publish site webapp¶
Generate the static HTML shell only (assumes payloads already exist).
Usage:
Options:
| Name | Type | Description | Default |
|---|---|---|---|
--output-repo-dir |
path | Path to the MAMUT-routing repo root. Defaults to $MAMUT_ROUTING_ROOT or the current working directory. | None |
--payload-mode |
text | How generated HTML shells should fetch route payloads ('static' or 'api'). | static |
--payload-api-prefix |
text | API prefix embedded into generated HTML shells when --payload-mode is 'api'. | /api/site-payload |
--payload-root-dir |
path | Directory under the site output root for route payload JSON files. | site-payloads |
--site-output-dir |
path | Directory where generated website files are written. Relative paths resolve under --output-repo-dir. | dist |
--basemap-api-key |
text | CARTO basemaps API key written into the workbench page so the map can use the CARTO Positron / Dark Matter vector basemaps. Without it the workbench map falls back to OpenStreetMap tiles. | None |
--help |
boolean | Show this message and exit. | False |