fix(docs): make docs deployable to subdir (#7479)

DennisOSRM · web-flow · commit a264ce0a7d5d · 2026-04-15T08:31:12.000+02:00
diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js
@@ -7,6 +7,7 @@ export default defineConfig({
   title: 'OSRM API Documentation',
   description: 'The Open Source Routing Machine API documentation',
   base: docsBase,
+  cleanUrls: true,
   ignoreDeadLinks: true,
 
   themeConfig: {
@@ -20,7 +21,7 @@ export default defineConfig({
       {
         text: 'Getting Started',
         items: [
-          { text: 'Introduction', link: '/' },
+          { text: 'Tool options', link: '/tools'},
           { text: 'Developing', link: '/developing' },
           { text: 'Testing', link: '/testing' },
           { text: 'Releasing', link: '/releasing' }
diff --git a/docs/cucumber.md b/docs/cucumber.md
@@ -11,7 +11,7 @@ This documentation describes the technical aspects of our cucumber test suite.
 Run the Cucumber tests with:
 
 ``` bash
-$ npm test -- --parallel 16
+$ npm test
 ```
 
 ## Single OSRM Configuration
@@ -74,7 +74,7 @@ configured port number (eg. at ports 5000--5000+N).
 We provide a shortcut to run all 6 configurations:
 
 ``` bash
-$ npm test -- --parallel 16
+$ npm test
 ```
 This is how the tests are run on the CI server. You can pass the same arguments as
 mentioned above.
@@ -129,7 +129,7 @@ arbitrarily although it is best to conform to the tags already used. Eg. the tag
 `@guidance` can be used to run only those tests related to the guidance feature:
 
 ``` bash
-$ npm test -- --parallel 16 --tags @guidance
+$ npm test -- --tags @guidance
 ```
 
 We also support following special tags:
diff --git a/docs/developing.md b/docs/developing.md
@@ -26,7 +26,7 @@ The field `data-for-conversion` can be an arbitrary long set of features and nee
 
 The policy itself offers a `operator()` accepting a `vector` of `NodeID`.
 
-For outputting data into our file (debug.geojson), we simply need to call the matching logging routine of the guard: `util::ScioedGeojsonLoggerGuard<util::NodeIdVectorToLineString>::Write(list_of_node_ids);`
+For outputting data into our file (debug.geojson), we simply need to call the matching logging routine of the guard: `util::ScopedGeojsonLoggerGuard<util::NodeIdVectorToLineString>::Write(list_of_node_ids);`
 (or `guard.Write(list_of_node_ids)` if you created an instance).
 
 ### Possible Scopeguard Location
@@ -57,6 +57,6 @@ If we want to use the same policy for multiple files, we need to use different t
 
 as well as,
  
-`util::ScopedGeojsonLoggerGuardr<util::NodeIdVectorToLineString,0>::Write(list_of_node_ids);`
+`util::ScopedGeojsonLoggerGuard<util::NodeIdVectorToLineString,0>::Write(list_of_node_ids);`
 
-`util::ScopedGeojsonLoggerGuardr<util::NodeIdVectorToLineString,1>::Write(list_of_node_ids);`
+`util::ScopedGeojsonLoggerGuard<util::NodeIdVectorToLineString,1>::Write(list_of_node_ids);`
diff --git a/docs/http.md b/docs/http.md
@@ -188,7 +188,7 @@ curl 'http://router.project-osrm.org/nearest/v1/driving/13.388860,52.517037?numb
          "location" : [
             13.388775,
             52.51717
-         ],
+         ]
       }
    ],
    "code" : "Ok"
@@ -476,7 +476,7 @@ The returned path does not have to be the fastest one. As TSP is NP-hard it only
 Note that all input coordinates have to be connected for the trip service to work.
 
 ```endpoint
-GET /trip/v1/{profile}/{coordinates}?roundtrip={true|false}&source{any|first}&destination{any|last}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}'
+GET /trip/v1/{profile}/{coordinates}?roundtrip={true|false}&source={any|first}&destination={any|last}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}
 ```
 
 In addition to the [general options](#general-options) the following options are supported for this service:
diff --git a/docs/index.md b/docs/index.md
@@ -15,6 +15,9 @@ hero:
     - theme: alt
       text: View on GitHub
       link: https://github.com/Project-OSRM/osrm-backend
+    - theme: alt
+      text: Sponsor ❤
+      link: https://github.com/sponsors/Project-OSRM
 
 features:
   - icon: 🚗
diff --git a/docs/testing.md b/docs/testing.md
@@ -4,7 +4,7 @@ OSRM comes with a testsuite containing both unit-tests using the Boost library a
 
 ## Unit Tests
 
-For a general introduction on Boost.Test have a look at [its docs](http://www.boost.org/doc/libs/1_60_0/libs/test/doc/html/index.html).
+For a general introduction on Boost.Test have a look at [its docs](https://www.boost.org/doc/libs/release/libs/test/doc/html/index.html).
 
 ### Separate Test Binaries
 
@@ -15,8 +15,8 @@ See `CMakeLists.txt` in the unit test directory for how to register new unit tes
 ### Using Boost.Test Primitives
 
 There is a difference between only reporting a failed condition and aborting the test right at a failed condition.
-Have a look at [`BOOST_CHECK` vs `BOOST_REQUIRE`](http://www.boost.org/doc/libs/1_60_0/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref/assertion_boost_level.html).
-Instead of manually checking e.g. for equality, less than, if a function throws etc. use their [corresponding Boost.Test primitives](http://www.boost.org/doc/libs/1_60_0/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref.html).
+Have a look at [`BOOST_CHECK` vs `BOOST_REQUIRE`](https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref/assertion_boost_level.html).
+Instead of manually checking e.g. for equality, less than, if a function throws etc. use their [corresponding Boost.Test primitives](https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/testing_tool_ref.html).
 
 If you use `BOOST_CHECK_EQUAL` you have to implement `operator<<` for your type so that Boost.Test can print mismatches.
 If you do not want to do this, define `BOOST_TEST_DONT_PRINT_LOG_VALUE` (and undef it after the check call) or sidestep it with `BOOST_CHECK(fst == snd);`.
diff --git a/docs/tools.md b/docs/tools.md
@@ -1,15 +1,25 @@
-# Common Tool Options
+# Command-Line Tools
 
-These options are available for all OSRM command-line tools:
-`osrm-extract`, `osrm-partition`, `osrm-customize`, `osrm-contract`, `osrm-routed`, and `osrm-datastore`.
+OSRM ships six command-line tools that cover the full data pipeline, from raw
+OSM data to a running routing server. All tools share a set of common options
+described below, followed by per-tool reference sections.
 
-## --list-inputs
+## Common Options
 
-Lists all required and optional input file extensions that the tool expects.
-Useful for deployment scripts that need to know which files to copy.
-Duplicate entries are suppressed when a tool combines multiple configs.
+These flags are accepted by every tool.
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--help` | `-h` | Show the help message and exit. |
+| `--version` | `-v` | Show the version string and exit. |
+| `--verbosity <level>` | `-l` | Log verbosity: `NONE`, `ERROR`, `WARNING`, `INFO` (default), `DEBUG`. |
+| `--list-inputs` | | Print all required and optional input file extensions the tool expects, then exit. Useful for deployment scripts. |
+| `--threads <n>` | `-t` | Number of threads to use (default: number of logical CPUs). |
+
+### `--list-inputs`
+
+Prints one line per file in the format `required|optional <extension>`:
 
-Example:
 ```
 $ osrm-routed --list-inputs
 required .osrm.datasource_names
@@ -20,19 +30,157 @@ optional .osrm.hsgr
 optional .osrm.cells
 ```
 
-```
-$ osrm-extract --list-inputs
-required .osrm.ebg
-required .osrm.ebg_nodes
-...
-```
-
-The output format is one line per file: `required|optional <extension>`.
-A deployment script can use this to determine the exact set of files needed:
+Example — collect all files needed to deploy `osrm-routed`:
 
 ```bash
 BASE=map
 for line in $(osrm-routed --list-inputs); do
     echo "$BASE$line"
 done
 ```
+
+---
+
+## osrm-extract
+
+Reads an OSM file and a Lua profile, and produces the intermediate `.osrm.*`
+files consumed by the graph-preparation tools.
+
+```
+osrm-extract <input.osm/.osm.bz2/.osm.pbf> [options]
+```
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--profile <path>` | `-p` | `profiles/car.lua` | Path to the Lua routing profile. |
+| `--output <path>` | `-o` | Derived from input filename | Base path for generated output files. |
+| `--data_version <string>` | `-d` | _(none)_ | Tag the dataset with a version string. Use `osmosis` to read the timestamp embedded in the PBF file. |
+| `--small-component-size <n>` | | `1000` | Minimum node count for a strongly-connected component to be treated as "large". Affects nearest-neighbor snapping. |
+| `--with-osm-metadata` | | | Parse OSM metadata (user, timestamp, etc.). May reduce extraction performance. |
+| `--parse-conditional-restrictions` | | | Save conditional turn restrictions to disk so they can be evaluated during contraction. |
+| `--location-dependent-data <file>` | | | GeoJSON files containing location-dependent data (e.g. speed limits by region). Repeatable. |
+| `--disable-location-cache` | | | Disable the internal node-location cache used for location-dependent data lookups. |
+| `--dump-nbg-graph` | | | Write the raw node-based graph to the `.osrm` file for debugging. |
+
+---
+
+## osrm-partition
+
+Partitions the road network graph into a hierarchy of cells used by the
+Multi-Level Dijkstra (MLD) algorithm.
+
+```
+osrm-partition <input.osrm> [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-cell-sizes <list>` | `128,4096,65536,2097152` | Comma-separated maximum cell sizes per level, starting from level 1. The first value is also the bisection termination threshold. |
+| `--balance <factor>` | `1.2` | Maximum allowed size ratio between the two sides of a single bisection. |
+| `--boundary <fraction>` | `0.25` | Fraction of nodes to use as boundary sources/sinks during contraction. |
+| `--optimizing-cuts <n>` | `10` | Number of candidate cuts evaluated when optimizing a single bisection. |
+| `--small-component-size <n>` | `1000` | Node-count threshold below which a component is treated as small. |
+
+---
+
+## osrm-customize
+
+Applies live traffic data (speed and turn-penalty files) to a partitioned MLD
+graph. Can be run repeatedly without re-partitioning when speeds change.
+
+```
+osrm-customize <input.osrm> [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--segment-speed-file <file>` | | CSV with `nodeA,nodeB,speed` columns to override edge weights. Repeatable. |
+| `--turn-penalty-file <file>` | | CSV with `from_node,via_node,to_node,penalty` to override turn weights. Repeatable. |
+| `--edge-weight-updates-over-factor <x>` | `0` (disabled) | Log edges whose weight changed by more than factor `x` (requires `--segment-speed-file`). |
+| `--parse-conditionals-from-now <utc_timestamp>` | `0` (disabled) | UTC Unix timestamp from which to evaluate conditional turn restrictions. |
+| `--time-zone-file <file>` | | GeoJSON file with time-zone boundaries, required for conditional restriction parsing. |
+
+---
+
+## osrm-contract
+
+Builds a Contraction Hierarchy (CH) from the extracted graph. Use this instead
+of `osrm-partition` + `osrm-customize` when you don't need live traffic updates.
+
+```
+osrm-contract <input.osrm> [options]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--segment-speed-file <file>` | | CSV with `nodeA,nodeB,speed` columns to override edge weights. Repeatable. |
+| `--turn-penalty-file <file>` | | CSV with `from_node,via_node,to_node,penalty` to override turn weights. Repeatable. |
+| `--edge-weight-updates-over-factor <x>` | `0` (disabled) | Log edges whose weight changed by more than factor `x`. |
+| `--parse-conditionals-from-now <utc_timestamp>` | `0` (disabled) | UTC Unix timestamp for evaluating conditional turn restrictions. |
+| `--time-zone-file <file>` | | GeoJSON file with time-zone boundaries, required for conditional restriction parsing. |
+
+---
+
+## osrm-routed
+
+The HTTP server. Loads a prepared dataset and serves the OSRM HTTP API.
+
+```
+osrm-routed <base.osrm> [options]
+```
+
+### Server
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--ip <address>` | `-i` | `0.0.0.0` | IP address to listen on. |
+| `--port <n>` | `-p` | `5000` | TCP port to listen on. |
+| `--keepalive-timeout <s>` | `-k` | `5` | HTTP keep-alive timeout in seconds. |
+| `--trial` | | | Start up fully, then exit immediately. Useful to validate a dataset without serving traffic. |
+
+### Data loading
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--algorithm <name>` | `-a` | `CH` | Routing algorithm: `CH` (Contraction Hierarchy) or `MLD` (Multi-Level Dijkstra). |
+| `--shared-memory` | `-s` | off | Load data from a shared memory region managed by `osrm-datastore`. |
+| `--mmap` | `-m` | off | Memory-map the data files instead of loading them into RAM. |
+| `--dataset-name <name>` | | | Shared memory dataset name to connect to (used with `--shared-memory`). |
+| `--disable-feature-dataset <name>` | | | Skip loading an optional dataset to save memory. Options: `ROUTE_STEPS`, `ROUTE_GEOMETRY`. |
+
+### Query limits
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--max-viaroute-size <n>` | `500` | Maximum number of waypoints in a route query. |
+| `--max-trip-size <n>` | `100` | Maximum number of locations in a trip query. |
+| `--max-table-size <n>` | `100` | Maximum number of locations in a table query. |
+| `--max-matching-size <n>` | `100` | Maximum number of locations in a map-matching query. |
+| `--max-nearest-size <n>` | `100` | Maximum number of results in a nearest query. |
+| `--max-alternatives <n>` | `3` | Maximum number of alternative routes (MLD only). |
+| `--max-matching-radius <m>` | `-1` (unlimited) | Maximum search radius in metres for map-matching. |
+| `--default-radius <m>` | `-1` (unlimited) | Default snap radius for all queries. |
+| `--max-header-size <bytes>` | `0` (auto) | Maximum HTTP header size in bytes. |
+
+---
+
+## osrm-datastore
+
+Loads a prepared dataset into shared memory so that one or more `osrm-routed`
+processes can serve it with zero-copy access. Enables live traffic updates
+without restarting the server.
+
+```
+osrm-datastore [options] <base.osrm>
+```
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--dataset-name <name>` | | | Name for this dataset in shared memory. Allows multiple datasets to coexist. |
+| `--max-wait <s>` | `-1` (unlimited) | Seconds to wait for a running update to finish before forcibly acquiring the lock. |
+| `--only-metric` | | | Reload only the metric (weights/durations) without replacing the full dataset. Optimized for frequent traffic updates. |
+| `--disable-feature-dataset <name>` | | | Skip loading an optional dataset. Options: `ROUTE_STEPS`, `ROUTE_GEOMETRY`. |
+| `--remove-locks` | `-r` | | Remove stale shared-memory locks and exit. |
+| `--spring-clean` | `-s` | | Remove all OSRM shared memory regions and exit. |
+| `--list` | | | List all datasets currently loaded in shared memory. |
+| `--list-blocks` | | | List all shared memory blocks currently in use. |
diff --git a/scripts/build_api_docs.sh b/scripts/build_api_docs.sh
@@ -7,6 +7,11 @@ if [ ! -f docs/http.md ] ; then
     exit 1
 fi
 
+# Optional: pass a subpath to serve the docs from, e.g. /docs/v1.2.3/
+# Usage: ./scripts/build_api_docs.sh /docs/v1.2.3/
+# Defaults to / for serving from the root of a static server.
+DOCS_BASE="${1:-/}"
+
 # Clean up previous version
 rm -rf build/docs
 
@@ -17,7 +22,7 @@ node scripts/extract_cpp_jsdoc.js src/nodejs/node_osrm.cpp > build/docs/jsdoc-ex
 npx documentation build build/docs/jsdoc-extract.js --markdown-toc=false -f md -o docs/nodejs/api.md
 
 # Build static site with VitePress
-npx vitepress build docs
+DOCS_BASE="${DOCS_BASE}" npx vitepress build docs
 
 # Copy the built site contents to build/docs (site root directly under build/docs)
 cp -a docs/.vitepress/dist/. build/docs/
