Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: versioning for documentation #1704

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

docs: versioning for documentation #1704

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cfa2efb
feat: add vitepress-versioning-plugin
Feb 28, 2024
df6a74f
refactor: use relative links
Feb 28, 2024
eae0aa3
feat: add template for versioned sidebars
Feb 28, 2024
919233c
docs: add CHANGELOG.md entry for docs versioning
Feb 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ RELEASING:
## [Unreleased]

### Added
- add versioning to docs using vitepress-versioning-plugin
- snapping service endpoints for returning nearest points on the graph ([#1519](https://github.com/GIScience/openrouteservice/issues/1519))
- workflow for RPM packaging ([#1490](https://github.com/GIScience/openrouteservice/pull/1490))
- workflow for graph building with GitHub environments ([#1468](https://github.com/GIScience/openrouteservice/pull/1468))
Expand Down
186 changes: 98 additions & 88 deletions docs/.vitepress/config.js
View file
Open in desktop

Large diffs are not rendered by default.

124 changes: 124 additions & 0 deletions docs/.vitepress/sidebars/versioned/template.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
[
{
"text": "Home", "link": "/",
"items": [
{"text": "Getting Started", "link": "/getting-started"},
{
"text": "API Reference", "collapsed": true, "link": "/api-reference/",
"items": [
{
"text": "Endpoints", "collapsed": true, "link": "/api-reference/endpoints/",
"items": [
{
"text": "Directions", "collapsed": true, "link": "/api-reference/endpoints/directions/",
"items": [
{"text": "Requests and Return Types", "link": "/api-reference/endpoints/directions/requests-and-return-types"},
{"text": "Routing Options", "link": "/api-reference/endpoints/directions/routing-options"},
{
"text": "Extra info", "collapsed": true, "link": "/api-reference/endpoints/directions/extra-info/",
"items": [
{"text": "Steepness IDs", "link": "/api-reference/endpoints/directions/extra-info/steepness"},
{"text": "Surface IDs", "link": "/api-reference/endpoints/directions/extra-info/surface"},
{"text": "Category IDs", "link": "/api-reference/endpoints/directions/extra-info/waycategory"},
{"text": "Type IDs", "link": "/api-reference/endpoints/directions/extra-info/waytype"},
{"text": "Difficulty IDs", "link": "/api-reference/endpoints/directions/extra-info/trail-difficulty"},
{"text": "Restriction IDs", "link": "/api-reference/endpoints/directions/extra-info/road-access-restrictions"},
{"text": "Country IDs", "link": "/technical-details/country-list"}
]
},
{"text": "Route Attributes", "link": "/api-reference/endpoints/directions/route-attributes"},
{"text": "Geometry Decoding", "link": "/api-reference/endpoints/directions/geometry-decoding"},
{"text": "Instruction Types", "link": "/api-reference/endpoints/directions/instruction-types"}
]
},
{"text": "Isochrones", "link": "/api-reference/endpoints/isochrones/"},
{"text": "Matrix", "link": "/api-reference/endpoints/matrix/"},
{"text": "Snapping (not live)", "link": "/api-reference/endpoints/snapping/"},
{"text": "Export (not live)", "link": "/api-reference/endpoints/export/"},
{"text": "Health (not live)", "link": "/api-reference/endpoints/health/"},
{"text": "Status (not live)", "link": "/api-reference/endpoints/status/"},
{"text": "POI", "link": "/api-reference/endpoints/poi/"},
{"text": "Elevation", "link": "/api-reference/endpoints/elevation/"},
{"text": "Geocoder", "link": "/api-reference/endpoints/geocoder/"},
{"text": "Optimization", "link": "/api-reference/endpoints/optimization/"}
]
},
{"text": "Error Codes", "link": "/api-reference/error-codes"}
]
},
{
"text": "Run ORS instance", "collapsed": true, "link": "/run-instance/",
"items": [
{"text": "System Requirements", "link": "/run-instance/system-requirements"},
{"text": "Data", "link": "/run-instance/data"},
{
"text": "Installation", "collapsed": true, "link": "/run-instance/installation/",
"items": [
{"text": "Running with Docker", "link": "/run-instance/installation/running-with-docker"},
{"text": "Running JAR / WAR", "link": "/run-instance/installation/running-jar-war"},
{"text": "Building from Source", "link": "/run-instance/installation/building-from-source"}
]
},
{
"text": "Configuration", "collapsed": true, "link": "/run-instance/configuration/",
"items": [
{"text": "Spring Properties", "link": "/run-instance/configuration/spring/", "collapsed":true,
"items": [
{"text": "server", "link": "/run-instance/configuration/spring/server.md"},
{"text": "logging", "link": "/run-instance/configuration/spring/logging.md"}
]
},
{"text": "ORS Properties", "collapsed":true,
"items": [
{"text": "endpoints", "link": "/run-instance/configuration/ors/endpoints/", "collapsed": true,
"items": [
{"text": "defaults", "link": "/run-instance/configuration/ors/endpoints/defaults.md"},
{"text": "routing", "link": "/run-instance/configuration/ors/endpoints/routing.md"},
{"text": "matrix", "link": "/run-instance/configuration/ors/endpoints/matrix.md"},
{"text": "isochrones", "link": "/run-instance/configuration/ors/endpoints/isochrones.md"},
{"text": "snap", "link": "/run-instance/configuration/ors/endpoints/snap.md"}
]
},
{"text": "engine", "link": "/run-instance/configuration/ors/engine/", "collapsed": true,
"items": [
{"text": "profiles", "link": "/run-instance/configuration/ors/engine/profiles.md"},
{"text": "elevation", "link": "/run-instance/configuration/ors/engine/elevation.md"}
]
},
{"text": "cors", "link": "/run-instance/configuration/ors/cors/"},
{"text": "messages", "link": "/run-instance/configuration/ors/messages/"}
]
},
{"text": "JSON config (deprecated)", "link":"/run-instance/configuration/json.md"}
]
}
]
},
{
"text": "Contributing", "collapsed": true, "link": "/contributing/",
"items": [
{"text": "Opening project in IntelliJ", "link": "/contributing/opening-project-in-intellij"},
{"text": "Backend documentation", "link": "/contributing/backend-documentation"},
{"text": "Contribution guidelines", "link": "https://github.com/GIScience/openrouteservice/blob/main/CONTRIBUTE.md"},
{"text": "Contributing translations", "link": "/contributing/contributing-translations"}
]
},
{
"text": "Technical details", "collapsed": true, "link": "/technical-details/",
"items": [
{"text": "Country List", "link": "/technical-details/country-list"},
{"text": "Travel Speeds", "link": "/technical-details/travel-speeds/",
"items": [
{"text": "Country Speeds", "link": "/technical-details/travel-speeds/country-speeds.md"},
{"text": "Tracktype Speeds", "link": "/technical-details/travel-speeds/tracktype-speeds.md"},
{"text": "Waytype Speeds", "link": "/technical-details/travel-speeds/waytype-speeds.md"},
{"text": "Surface Speeds", "link": "/technical-details/travel-speeds/surface-speeds.md"}
]
},
{"text": "Tag Filtering", "link": "/technical-details/tag-filtering"}
]
},
{"text": "FAQ", "link": "/frequently-asked-questions"}
]
}
]
6 changes: 3 additions & 3 deletions docs/contributing/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ please use the [corresponding repository](https://github.com/GIScience/ors-maps-

## Contributing code

To help you get started, here is a document describing how to [open the code in IntelliJ](opening-project-in-intellij).
To help you get started, here is a document describing how to [open the code in IntelliJ](./opening-project-in-intellij).
We also put together a few [guidelines](https://github.com/GIScience/openrouteservice/blob/main/CONTRIBUTE.md)
to help you in the process and keep the repository clean and tidy.

## Other ways to contribute

* [Contributing translations](contributing-translations)
* [Contributing to this documentation](backend-documentation)
* [Contributing translations](./contributing-translations)
* [Contributing to this documentation](./backend-documentation)
* [Updating OpenStreetMap](https://wiki.openstreetmap.org/wiki/Beginners%27_guide)
6 changes: 3 additions & 3 deletions docs/frequently-asked-questions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ There are three main reasons for this problem, listed in order of most to least
road. The maximum distance for snapping to road segments in our API is 350m.
This can be customized for local installations via the
`maximum_snapping_radius` and `location_index_resolution` config-parameter. See
[configuration](/run-instance/configuration/ors/engine/profiles.md) for details.
[configuration](./run-instance/configuration/ors/engine/profiles.md) for details.

3. The start and endpoint are passed with correct lon,lat-order and are within
350m of a routable road. This should only happen with a local installation.
Expand All @@ -48,7 +48,7 @@ be preprocessed before the openrouteservice can start building the graphs used
for routing.

The build process in itself is [rather
resource-intensive](/run-instance/system-requirements.md). It takes roughly two
resource-intensive](./run-instance/system-requirements.md). It takes roughly two
days for any one of the nine profiles. For the mentioned resource requirements,
this means that it will take roughly a week for all profiles to be re-built.

Expand All @@ -69,4 +69,4 @@ concern, if changes are not reflected within a month.

## I get an Error `Native memory allocation (mmap) failed to map 16384 bytes for committing reserved memory`

See memory mapping section in [system requirements](/run-instance/system-requirements.md#memory-mapping-in-large-builds-with-a-containerized-openrouteservice-instance).
See memory mapping section in [system requirements](./run-instance/system-requirements.md#memory-mapping-in-large-builds-with-a-containerized-openrouteservice-instance).
28 changes: 14 additions & 14 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@

The fastest way to get to the info you are looking for is **the search bar above**. If that doesn't work, the sidebar has you covered:

* The [API Reference](api-reference/index.md) contains info about openrouteservice's API [endpoints](api-reference/endpoints/index.md) and usage, both for using the [public API](https://openrouteservice.org/dev/#/api-docs) and using locally run instances of openrouteservice.
* [Directions](api-reference/endpoints/directions/index.md) endpoint
* [Isochrones](api-reference/endpoints/isochrones/index.md) endpoint
* [Matrix](api-reference/endpoints/matrix/index.md) endpoint
* [Snapping](api-reference/endpoints/snapping/index.md) endpoint _(not available in our live API)_
* [Export](api-reference/endpoints/export/index.md) endpoint _(not available in our live API)_
* [Run ORS instance](run-instance/index.md) contains all info about setting up the ors locally.
* [System requirements](run-instance/system-requirements)
* [Data](run-instance/data) used by openrouteservice
* [Installation](run-instance/installation/index.md) either directly using [JAR / WAR](run-instance/installation/running-jar-war) artifacts, with [Docker](run-instance/installation/running-with-docker) or [building from source](run-instance/installation/building-from-source)
* [Configuration](run-instance/configuration/index.md) of openrouteservice instances
* [Contributing](contributing/index.md) contains info about contributing to the openrouteservice, the OpenStreetMap and [translations](contributing/contributing-translations)
* [Technical details](technical-details/index.md) contains all sorts of explanation about the internal workings of the openrouteservice.
* [FAQ](frequently-asked-questions) contains answers to frequently asked questions.
* The [API Reference](./api-reference/index.md) contains info about openrouteservice's API [endpoints](./api-reference/endpoints/index.md) and usage, both for using the [public API](https://openrouteservice.org/dev/#/api-docs) and using locally run instances of openrouteservice.
* [Directions](./api-reference/endpoints/directions/index.md) endpoint
* [Isochrones](./api-reference/endpoints/isochrones/index.md) endpoint
* [Matrix](./api-reference/endpoints/matrix/index.md) endpoint
* [Snapping](./api-reference/endpoints/snapping/index.md) endpoint _(not available in our live API)_
* [Export](./api-reference/endpoints/export/index.md) endpoint _(not available in our live API)_
* [Run ORS instance](./run-instance/index.md) contains all info about setting up the ors locally.
* [System requirements](./run-instance/system-requirements)
* [Data](./run-instance/data) used by openrouteservice
* [Installation](./run-instance/installation/index.md) either directly using [JAR / WAR](./run-instance/installation/running-jar-war) artifacts, with [Docker](./run-instance/installation/running-with-docker) or [building from source](./run-instance/installation/building-from-source)
* [Configuration](./run-instance/configuration/index.md) of openrouteservice instances
* [Contributing](./contributing/index.md) contains info about contributing to the openrouteservice, the OpenStreetMap and [translations](./contributing/contributing-translations)
* [Technical details](./technical-details/index.md) contains all sorts of explanation about the internal workings of the openrouteservice.
* [FAQ](./frequently-asked-questions) contains answers to frequently asked questions.

For a more general overview, visit our website at [openrouteservice.org](https://openrouteservice.org).

Expand Down
10 changes: 5 additions & 5 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,26 @@ hero:
actions:
- theme: brand
text: Getting Started
link: /getting-started
link: ./getting-started
- theme: alt
text: API Playground
link: https://openrouteservice.org/dev/#/api-docs/v2/directions/{profile}/post
- theme: alt
text: Contributing
link: /contributing/
link: ./contributing/
- theme: alt
text: Reference
link: /api-reference/
link: ./api-reference/

features:
- title: Installation
details: Set up your own openrouteservice instance.
linkText: Instructions
link: /run-instance/installation/
link: ./run-instance/installation/
- title: Data Sources
details: Find all information on the data used by the openrouteservice here.
linkText: Data
link: /run-instance/data
link: ./run-instance/data
- title: Latest Changes
details: Check out the latest changes to the openrouteservice.
linkText: CHANGELOG.md
Expand Down
22 changes: 11 additions & 11 deletions docs/run-instance/configuration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The recommended way to configure your own openrouteservice instance is with a YAML configuration file.

In the past openrouteservice was configured [via JSON file](json.md). This configuration method has been **deprecated** and will be eventually removed, therefore we strongly discourage you from using it.
In the past openrouteservice was configured [via JSON file](./json.md). This configuration method has been **deprecated** and will be eventually removed, therefore we strongly discourage you from using it.

## File location

Expand Down Expand Up @@ -32,8 +32,8 @@ At program start openrouteservice reports which configuration file was loaded.

You can find an [example configuration file](https://github.com/GIScience/openrouteservice/blob/main/ors-config.yml) with most available configuration options.

At the very least, openrouteservice needs the configuration to contain an enabled [profile](ors/engine/profiles.md) and the
reference to an [OSM data file](/run-instance/data.md#osm-data) to run properly. Therefore, the minimal valid content of such a file
At the very least, openrouteservice needs the configuration to contain an enabled [profile](./ors/engine/profiles.md) and the
reference to an [OSM data file](../data.md#osm-data) to run properly. Therefore, the minimal valid content of such a file
would be, e.g.:

```yaml
Expand All @@ -47,14 +47,14 @@ ors:

The properties are organized in a hierarchical structure, with the following ones at top level.

- [Spring Properties](spring/index.md), such as
* [Server Properties](spring/server.md)
* [Logging Properties](spring/logging.md)
- [Spring Properties](./spring/index.md), such as
* [Server Properties](./spring/server.md)
* [Logging Properties](./spring/logging.md)
- openrouteservice properties with these children:
* [ors.endpoints](ors/endpoints/index.md): Settings required at runtime to process API requests.
* [ors.engine](ors/engine/index.md): Settings required at graph-build time during startup.
* [ors.cors](ors/cors/index.md): Cross-origin resource sharing settings.
* [ors.messages](ors/messages/index.md): System messages that can be sent with API responses following simple rules.
* [ors.endpoints](./ors/endpoints/index.md): Settings required at runtime to process API requests.
* [ors.engine](./ors/engine/index.md): Settings required at graph-build time during startup.
* [ors.cors](./ors/cors/index.md): Cross-origin resource sharing settings.
* [ors.messages](./ors/messages/index.md): System messages that can be sent with API responses following simple rules.


## Alternative configuration
Expand All @@ -77,7 +77,7 @@ The options in order of precedence (higher options win over lower) are:
java -jar ors.jar
```

The option to configure using environment variables is especially useful in contexts where you want to run openrouteservice in containers such as with [docker](/run-instance/installation/running-with-docker.md).
The option to configure using environment variables is especially useful in contexts where you want to run openrouteservice in containers such as with [docker](../installation/running-with-docker.md).

Every property also corresponds to an environment variable name in *uppercase letters* and with *underscores* replacing *dots*, so e.g.
- `ORS_ENGINE_SOURCE_FILE` replaces `ors.engine.source_file`
Expand Down
Loading
Loading