Skip to content

Commit

Permalink
docs: documentation overhaul (#1651)
Browse files Browse the repository at this point in the history
  • Loading branch information
@takb
takb authored Feb 13, 2024
2 parents e7b3bad + 921e6be commit 9b54204
Show file tree
Hide file tree
Showing 113 changed files with 3,968 additions and 2,257 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ docker/
# Ignore all ors-config files except for the sample one, useful for development and testing
ors-api/src/main/resources/ors-config*
!ors-api/src/main/resources/ors-config-sample.json
ors-api/ors-config.yml

envs/
ors-config-repo/
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ RELEASING:
- move APIEnums into API module ([#1634](https://github.com/GIScience/openrouteservice/issues/1634))
- performance improvements to isochrone calculations ([#1607](https://github.com/GIScience/openrouteservice/pull/1607))
- do not apply speed penalty to roads tagged with "access=destination" when computing isochrones ([#1682](https://github.com/GIScience/openrouteservice/pull/1682))
- backend documentation overhaul ([#1651](https://github.com/GIScience/openrouteservice/pull/1651))

### Deprecated
- JSON configuration and related classes ([#1506](https://github.com/GIScience/openrouteservice/pull/1506))
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

The **openrouteservice API** provides global spatial services by consuming user-generated and collaboratively collected free geographic data directly from [OpenStreetMap](http://www.openstreetmap.org). It is highly customizable, performant and written in Java.

The following services are available via a HTTP interface served by Tomcat.
The following services are available via an HTTP interface served by Tomcat.
- **Directions** - Returns a route between two or more locations for a selected profile with customizable additional settings and instructions.
- **Isochrones** - Obtains areas of reachability from given locations.
- **Matrix** - Computes one-to-many, many-to-one or many-to-many routes for any mode of transport provided by openrouteservice.
Expand Down Expand Up @@ -65,7 +65,7 @@ For instructions on how to [build from source](https://GIScience.github.io/openr

## Usage

Openrouteservice offers a set of endpoints for different spatial purposes. By default they will be available at
Openrouteservice offers a set of endpoints for different spatial purposes. By default, they will be available at

- `http://localhost:8080/ors/v2/directions`
- `http://localhost:8080/ors/v2/isochrones`
Expand All @@ -75,7 +75,7 @@ You can find more information in the [Installation and Usage Instructions](https

## API Documentation

For an easy and interactive way to test the api, visit our API documentation at [openrouteservice.org](https://openrouteservice.org/dev/#/api-docs).
For an easy and interactive way to test the api, visit our [API Playground](https://openrouteservice.org/dev/#/api-docs).
After obtaining your key you can try out the different endpoints instantly and start firing requests.


Expand Down
2 changes: 1 addition & 1 deletion docker-compose.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ services:
- "8080:8080"
- "9001:9001"
image: openrouteservice/openrouteservice:nightly
# For versioned images see https://giscience.github.io/openrouteservice/installation/Running-with-Docker.html
# For versioned images see https://giscience.github.io/openrouteservice/run-instance/installation/running-with-docker
user: "${UID:-0}:${GID:-0}"
# build:
# context: ./
Expand Down
2 changes: 1 addition & 1 deletion docker-entrypoint.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
echo "Running container as user $(whoami) with id $(id -u)"

if [[ -d /ors-core ]] || [[ -d /ors-conf ]]; then
echo "You're mounting old paths. Remove them and migrate to the new docker setup: https://giscience.github.io/openrouteservice/installation/Running-with-Docker.html"
echo "You're mounting old paths. Remove them and migrate to the new docker setup: https://giscience.github.io/openrouteservice/run-instance/installation/running-with-docker"
echo "Exit setup due to old folders /ors-core or /ors-conf being mounted"
sleep 5
exit 1
Expand Down
153 changes: 104 additions & 49 deletions docs/.vitepress/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ export default defineConfig({
base: "/openrouteservice/",
head: [['link', {rel: 'icon', href: '/openrouteservice/ors_fav.png'}]],
cleanUrls: true,
ignoreDeadLinks: 'localhostLinks',
markdown: {
languageAlias: {
'jsonpath': 'json'
}
},
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
siteTitle: false,
Expand Down Expand Up @@ -34,81 +40,130 @@ export default defineConfig({
},
nav: [
{text: 'Homepage', link: 'https://openrouteservice.org'},
{text: 'Forum', link: 'https://ask.openrouteservice.org'},
{text: 'API Playground', link: 'https://openrouteservice.org/dev/#/api-docs'},
{text: 'Forum', link: 'https://ask.openrouteservice.org'},
],
sidebar: [
{
text: 'Home', link: '/',
items: [
{text: 'Getting Started', link: '/getting-started'},
{
text: 'Installation and Usage', collapsed: true, link: '/installation/Installation-and-Usage',
text: 'API Reference', collapsed: true, link: '/api-reference/',
items: [
{text: 'Running with Docker', link: '/installation/Running-with-Docker'},
{text: 'Building from Source', link: '/installation/Building-from-Source'},
{text: 'System Requirements', link: '/installation/System-Requirements'},
{text: 'Configuration', link: '/installation/Configuration'},
{text: 'Advanced Docker Setup', link: '/installation/Advanced-Docker-Setup'},
{text: 'Backend Documentation', link: '/installation/Backend-Documentation'}
]
},
{text: 'Data', link: '/Data'},
{
text: 'Contributing', collapsed: true, link: '/contributing/Contributing',
items: [
{text: 'Contributing Translations', link: '/contributing/Contributing-Translations'}
{
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: 'Documentation', collapsed: true, link: '/documentation/Documentation',
text: 'Run ORS instance', collapsed: true, link: '/run-instance/',
items: [
{text: 'Tag Filtering', link: '/documentation/Tag-Filtering'},
{text: 'System Requirements', link: '/run-instance/system-requirements'},
{text: 'Data', link: '/run-instance/data'},
{
text: 'Travel Speeds',
collapsed: true,
link: '/documentation/travel-speeds/Travel-Speeds',
text: 'Installation', collapsed: true, link: '/run-instance/installation/',
items: [
{text: 'Waytype Speeds', link: '/documentation/travel-speeds/Waytype-Speeds'},
{text: 'Surface Speeds', link: '/documentation/travel-speeds/Surface-Speeds'},
{text: 'Tracktype Speeds', link: '/documentation/travel-speeds/Tracktype-Speeds'},
{text: 'Country Speeds', link: '/documentation/travel-speeds/Country-Speeds'}
{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: 'Route Attributes', link: '/documentation/Route-Attributes'},
{
text: 'Routing Options',
collapsed: true,
link: '/documentation/routing-options/Routing-Options',
text: 'Configuration', collapsed: true, link: '/run-instance/configuration/',
items: [
{text: 'Examples', link: '/documentation/routing-options/Examples'},
{text: 'Country List', link: '/documentation/routing-options/Country-List'},
{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: 'Instruction Types', link: '/documentation/Instruction-Types'},
{
text: 'Extra Info', collapsed: true, link: '/documentation/extra-info/Extra-Info',
]
},
{
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: 'Steepness', link: '/documentation/extra-info/Steepness'},
{text: 'Surface', link: '/documentation/extra-info/Surface'},
{text: 'Waycategory', link: '/documentation/extra-info/Waycategory'},
{text: 'Waytype', link: '/documentation/extra-info/Waytype'},
{text: 'Trail Difficulty', link: '/documentation/extra-info/Trail-Difficulty'},
{
text: 'Road Access Restrictions',
link: '/documentation/extra-info/Road-Access-Restrictions'
}
{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: 'Geometry Decoding', link: '/documentation/Geometry-Decoding'},
{text: 'Structured Geocoding Query', link: '/documentation/Structured-Geocoding-Query'},
{text: 'Matrix Response', link: '/documentation/Matrix-Response'},
{text: 'Places Request and Response', link: '/documentation/Places-Request-and-Response'},
{text: 'Geocoding Response', link: '/documentation/Geocoding-Response'},
{text: 'Error Codes', link: '/documentation/Error-Codes'},
{text: 'Tag Filtering', link: '/technical-details/tag-filtering'}
]
},
{text: 'FAQ', link: '/Frequently-Asked-Questions'}
{text: 'FAQ', link: '/frequently-asked-questions'}
]
}
],
Expand Down
22 changes: 0 additions & 22 deletions docs/Data.md
View file

This file was deleted.

Loading

0 comments on commit 9b54204

Please sign in to comment.