From 4dc5a63d3ab08df42cf8159e77e2c9cd7fb4c846 Mon Sep 17 00:00:00 2001 From: Richard Kettelerij Date: Sat, 19 Oct 2024 00:34:29 +0200 Subject: [PATCH] chore(docs): describe configuration file by automatically generating docs from the Config structs --- README.md | 6 +- config/config.go | 1 + docs/README.md | 294 +++++++++++++++++++++++++++++++++++ hack/generate-config-docs.sh | 20 +++ 4 files changed, 319 insertions(+), 2 deletions(-) create mode 100644 docs/README.md create mode 100755 hack/generate-config-docs.sh diff --git a/README.md b/README.md index 4b02ca92..6b6334e7 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,11 @@ docker run -v `pwd`/examples:/examples -p 8080:8080 -it pdok/gokoala --config-fi Now open . See [examples](examples) for more details. -### Configuration file +## Config -The configuration file consists of a general section and a section +See the full **[Configuration Reference](./docs/README.md)** for available options. + +The configuration YAML file consists of a general section and a section per OGC API building block (tiles, styles, etc). See [example configuration files](examples/) for details. You can reference environment variables in the configuration file. For example to use the `MY_SERVER` env var: diff --git a/config/config.go b/config/config.go index d167c8ed..7e3d56d0 100644 --- a/config/config.go +++ b/config/config.go @@ -1,4 +1,5 @@ //go:generate ../hack/generate-deepcopy.sh +//go:generate ../hack/generate-config-docs.sh package config import ( diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..d915d8c5 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,294 @@ +# Configuration Reference ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|version|[string](#string)|true| |Version of the API. When releasing a new version which contains backwards-incompatible changes, a new major version must be released.| +|title|[string](#string)|true| |Human friendly title of the API. Don't include "OGC API" in the title, this is added automatically.| +|serviceIdentifier|[string](#string)|true| |Shorted title / abbreviation describing the API.| +|abstract|[string](#string)|true| |Human friendly description of the API and dataset.| +|license|[License](#License)|true| |Licensing term that apply to this API and dataset.| +|baseUrl|[URL](#URL)|true| |The base URL - that's the part until the OGC API landing page - under which this API is served.| +|datasetCatalogUrl|[URL](#URL)|false| |Optional reference to a catalog/portal/registry that lists all datasets, not just this one
+optional.| +|availableLanguages.[] |[Language](#Language)|false| |The languages/translations to offer, valid options are Dutch (nl) and English (en). Dutch is the default.
+optional.| +|ogcApi|[OgcAPI](#OgcAPI)|true| |Define which OGC API building blocks this API supports.| +|collectionOrder.[] |[string](#string)|false| |Order in which collections (containing features, tiles, 3d tiles, etc.) should be returned.
When not specified collections are returned in alphabetic order.
+optional.| +|thumbnail|[string](#string)|false| |Reference to a PNG image to use a thumbnail on the landing page.
The full path is constructed by appending Resources + Thumbnail.
+optional.| +|keywords.[] |[string](#string)|false| |Keywords to make this API beter discoverable
+optional.| +|lastUpdated|[string](#string)|false| |Moment in time when the dataset was last updated
+optional
+kubebuilder:validation:Type=string
+kubebuilder:validation:Format="date-time".| +|lastUpdatedBy|[string](#string)|false| |Who updated the dataset
+optional.| +|support|[Support](#Support)|false| |Available support channels
+optional.| +|datasetDetails.[] |[DatasetDetail](#DatasetDetail)|false| |Key/value pairs to add extra information to the landing page
+optional.| +|resources|[Resources](#Resources)|false| |Location where resources (e.g. thumbnails) specific to the given dataset are hosted
+optional.| + +## License ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|name|[string](#string)|true| |Name of the license, e.g. MIT, CC0, etc.| +|url|[URL](#URL)|true| |URL to license text on the web.| + +## URL +URL Custom net.URL compatible with YAML and JSON (un)marshalling and kubebuilder. +In addition, it also removes trailing slash if present, so we can easily +append a longer path without having to worry about double slashes. + +Allow only http/https URLs or environment variables like ${FOOBAR} ++kubebuilder:validation:Pattern=`^(https?://.+)|(\$\{.+\}.*)` ++kubebuilder:validation:Type=string. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| + +## Language +Language represents a BCP 47 language tag. ++kubebuilder:validation:Type=string. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| + +## OgcAPI ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|3dgeovolumes|[OgcAPI3dGeoVolumes](#OgcAPI3dGeoVolumes)|false| |Enable when this API should offer OGC API 3D GeoVolumes. This includes OGC 3D Tiles.
+optional.| +|tiles|[OgcAPITiles](#OgcAPITiles)|false| |Enable when this API should offer OGC API Tiles. This also requires OGC API Styles.
+optional.| +|styles|[OgcAPIStyles](#OgcAPIStyles)|false| |Enable when this API should offer OGC API Styles.
+optional.| +|features|[OgcAPIFeatures](#OgcAPIFeatures)|false| |Enable when this API should offer OGC API Features.
+optional.| +|processes|[OgcAPIProcesses](#OgcAPIProcesses)|false| |Enable when this API should offer OGC API Processes.
+optional.| + +## Support ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|name|[string](#string)|true| |Name of the support organization.| +|url|[URL](#URL)|true| |URL to external support webpage
+kubebuilder:validation:Type=string.| +|email|[string](#string)|false| |Email for support questions
+optional.| + +## DatasetDetail ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|name|[string](#string)|true| |Arbitrary name to add extra information to the landing page.| +|value|[string](#string)|true| |Arbitrary value associated with the given name.| + +## Resources ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|url|[URL](#URL)|false| |Location where resources (e.g. thumbnails) specific to the given dataset are hosted. This is optional if Directory is set
+optional.| +|directory|[string](#string)|false| |// Location where resources (e.g. thumbnails) specific to the given dataset are hosted. This is optional if URL is set
+optional.| + +## OgcAPI3dGeoVolumes ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|tileServer|[URL](#URL)|true| |Reference to the server (or object storage) hosting the 3D Tiles.| +|collections|[GeoSpatialCollections](#GeoSpatialCollections)|true| |Collections to be served as 3D GeoVolumes.| +|validateResponses|[bool](#bool)|false|true|Whether JSON responses will be validated against the OpenAPI spec
since it has significant performance impact when dealing with large JSON payloads.

+kubebuilder:default=true
+optional.ptr due to https://github.com/creasty/defaults/issues/49.| + +## OgcAPITiles ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|tileServer|[URL](#URL)|true| |Reference to the server (or object storage) hosting the tiles.
Note: Only marked as optional in CRD to support top-level OR collection-level tiles
+optional.| +|types.[] |[TilesType](#TilesType)|true| |Could be 'vector' and/or 'raster' to indicate the types of tiles offered
Note: Only marked as optional in CRD to support top-level OR collection-level tiles
+optional.| +|supportedSrs.[] |[SupportedSrs](#SupportedSrs)|true| |Specifies in what projections (SRS/CRS) the tiles are offered
Note: Only marked as optional in CRD to support top-level OR collection-level tiles
+optional.| +|uriTemplateTiles|[string](#string)|false| |Optional template to the vector tiles on the tileserver. Defaults to {tms}/{z}/{x}/{y}.pbf.
+optional.| +|collections|[GeoSpatialCollections](#GeoSpatialCollections)|false| |Tiles per collection. When no collections are specified tiles should be hosted at the root of the API (/tiles endpoint).
+optional.| + +## OgcAPIStyles ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|default|[string](#string)|true| |ID of the style to use a default.| +|stylesDir|[string](#string)|true| |Location on disk where the styles are hosted.| +|supportedStyles.[] |[Style](#Style)|true| |Styles exposed though this API.| + +## OgcAPIFeatures ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|basemap|[string](#string)|false|OSM|Basemap to use in embedded viewer on the HTML pages.
+kubebuilder:default="OSM"
+kubebuilder:validation:Enum=OSM;BRT
+optional.| +|collections|[GeoSpatialCollections](#GeoSpatialCollections)|true| |Collections to be served as features through this API.| +|limit|[Limit](#Limit)|false| |Limits the amount of features to retrieve with a single call
+optional.| +|datasources|[Datasources](#Datasources)|false| |One or more datasources to get the features from (geopackages, postgis, etc).
Optional since you can also define datasources at the collection level
+optional.| +|validateResponses|[bool](#bool)|false|true|Whether GeoJSON/JSON-FG responses will be validated against the OpenAPI spec
since it has significant performance impact when dealing with large JSON payloads.

+kubebuilder:default=true
+optional.ptr due to https://github.com/creasty/defaults/issues/49.| + +## OgcAPIProcesses ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|supportsDismiss|[bool](#bool)|true| |Enable to advertise dismiss operations on the conformance page.| +|supportsCallback|[bool](#bool)|true| |Enable to advertise callback operations on the conformance page.| +|processesServer|[URL](#URL)|true| |Reference to an external service implementing the process API. GoKoala acts only as a proxy for OGC API Processes.| + +## TilesType +**Type:** string ++kubebuilder:validation:Enum=raster;vector. + +| Enum Value | Describe | +|----------|--------------| +|"raster"|| +|"vector"|| + +## SupportedSrs ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|srs|[string](#string)|true| |Projection (SRS/CRS) used
+kubebuilder:validation:Pattern=`^EPSG:\d+$`.| +|zoomLevelRange|[ZoomLevelRange](#ZoomLevelRange)|true| |Available zoom levels.| + +## Style ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|id|[string](#string)|true| |Unique ID of this style.| +|title|[string](#string)|true| |Human-friendly name of this style.| +|description|[string](#string)|false| |Explains what is visualized by this style
+optional.| +|keywords.[] |[string](#string)|false| |Keywords to make this style better discoverable
+optional.| +|lastUpdated|[string](#string)|false| |Moment in time when the style was last updated
+optional
+kubebuilder:validation:Type=string
+kubebuilder:validation:Format="date-time".| +|version|[string](#string)|false| |Optional version of this style
+optional.| +|thumbnail|[string](#string)|false| |Reference to a PNG image to use a thumbnail on the style metadata page.
The full path is constructed by appending Resources + Thumbnail.
+optional.| +|formats.[] |[StyleFormat](#StyleFormat)|true| |This style is offered in the following formats.| + +## Limit ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|default|[int](#int)|false|10|Number of features to return by default.
+kubebuilder:default=10
+kubebuilder:validation:Minimum=2
+optional.| +|max|[int](#int)|false|1000|Max number of features to return. Should be larger than 100 since the HTML interface always offers a 100 limit option.
+kubebuilder:default=1000
+kubebuilder:validation:Minimum=100
+optional.| + +## Datasources ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|defaultWGS84|[Datasource](#Datasource)|true| |Features should always be available in WGS84 (according to spec).
This specifies the datasource to be used for features in the WGS84 projection.| +|additional.[] |[AdditionalDatasource](#AdditionalDatasource)|true| |One or more additional datasources for features in other projections. GoKoala doesn't do
any on-the-fly reprojection so additional datasources need to be reprojected ahead of time.
+optional.| + +## ZoomLevelRange ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|start|[int](#int)|true| |Start zoom level
+kubebuilder:validation:Minimum=0.| +|end|[int](#int)|true| |End zoom level.| + +## StyleFormat ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|format|[string](#string)|false|mapbox|Name of the format
+kubebuilder:default="mapbox"
+optional.| + +## Datasource ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|geopackage|[GeoPackage](#GeoPackage)|false| |GeoPackage to get the features from.
+optional.| +|postgis|[PostGIS](#PostGIS)|false| |PostGIS database to get the features from (not implemented yet).
+optional.| + +## AdditionalDatasource ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|srs|[string](#string)|true| |Projection (SRS/CRS) used for the features in this datasource
+kubebuilder:validation:Pattern=`^EPSG:\d+$`.| +|geopackage|[GeoPackage](#GeoPackage)|false| |GeoPackage to get the features from.
+optional.| +|postgis|[PostGIS](#PostGIS)|false| |PostGIS database to get the features from (not implemented yet).
+optional.| + +## GeoPackage ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|local|[GeoPackageLocal](#GeoPackageLocal)|false| |Settings to read a GeoPackage from local disk
+optional.| +|cloud|[GeoPackageCloud](#GeoPackageCloud)|false| |Settings to read a GeoPackage as a Cloud-Backed SQLite database
+optional.| + +## PostGIS ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| + +## GeoPackageLocal ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|fid|[string](#string)|false|fid|Feature id column name
+kubebuilder:default="fid"
+optional.| +|externalFid|[string](#string)|true| |External feature id column name. When specified this ID column will be exposed to clients instead of the regular FID column.
It allows one to offer a more stable ID to clients instead of an auto-generated FID. External FID column should contain UUIDs.
+optional.| +|queryTimeout|[Duration](#Duration)|false|15s|Optional timeout after which queries are canceled
+kubebuilder:default="15s"
+optional.| +|maxBBoxSizeToUseWithRTree|[int](#int)|false|8000|ADVANCED SETTING. When the number of features in a bbox stay within the given value use an RTree index, otherwise use a BTree index.
+kubebuilder:default=8000
+optional.| +|inMemoryCacheSize|[int](#int)|false|-2000|ADVANCED SETTING. Sets the SQLite "cache_size" pragma which determines how many pages are cached in-memory.
See https://sqlite.org/pragma.html#pragma_cache_size for details.
Default in SQLite is 2000 pages, which equates to 2000KiB (2048000 bytes). Which is denoted as -2000.
+kubebuilder:default=-2000
+optional.| +|file|[string](#string)|true| |Location of GeoPackage on disk.
You can place the GeoPackage here manually (out-of-band) or you can specify Download
and let the application download the GeoPackage for you and store it at this location.| +|download|[GeoPackageDownload](#GeoPackageDownload)|false| |Optional initialization task to download a GeoPackage during startup. GeoPackage will be
downloaded to local disk and stored at the location specified in File.
+optional.| + +## GeoPackageCloud ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|fid|[string](#string)|false|fid|Feature id column name
+kubebuilder:default="fid"
+optional.| +|externalFid|[string](#string)|true| |External feature id column name. When specified this ID column will be exposed to clients instead of the regular FID column.
It allows one to offer a more stable ID to clients instead of an auto-generated FID. External FID column should contain UUIDs.
+optional.| +|queryTimeout|[Duration](#Duration)|false|15s|Optional timeout after which queries are canceled
+kubebuilder:default="15s"
+optional.| +|maxBBoxSizeToUseWithRTree|[int](#int)|false|8000|ADVANCED SETTING. When the number of features in a bbox stay within the given value use an RTree index, otherwise use a BTree index.
+kubebuilder:default=8000
+optional.| +|inMemoryCacheSize|[int](#int)|false|-2000|ADVANCED SETTING. Sets the SQLite "cache_size" pragma which determines how many pages are cached in-memory.
See https://sqlite.org/pragma.html#pragma_cache_size for details.
Default in SQLite is 2000 pages, which equates to 2000KiB (2048000 bytes). Which is denoted as -2000.
+kubebuilder:default=-2000
+optional.| +|connection|[string](#string)|true| |Reference to the cloud storage (either azure or google at the moment).
For example 'azure?emulator=127.0.0.1:10000&sas=0' or 'google'.| +|user|[string](#string)|true| |Username of the storage account, like devstoreaccount1 when using Azurite.| +|auth|[string](#string)|true| |Some kind of credential like a password or key to authenticate with the storage backend, e.g:
'Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==' when using Azurite.| +|container|[string](#string)|true| |Container/bucket on the storage account.| +|file|[string](#string)|true| |Filename of the GeoPackage.| +|cache|[GeoPackageCloudCache](#GeoPackageCloudCache)|false| |Local cache of fetched blocks from cloud storage
+optional.| +|logHttpRequests|[bool](#bool)|false|false|ADVANCED SETTING. Only for debug purposes! When true all HTTP requests executed by sqlite to cloud object storage are logged to stdout
+kubebuilder:default=false
+optional.| + +## Duration +Duration Custom time.Duration compatible with YAML and JSON (un)marshalling and kubebuilder. +(Already supported in yaml/v3 but not encoding/json.) + ++kubebuilder:validation:Type=string ++kubebuilder:validation:Format=duration. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| + +## GeoPackageDownload ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|from|[URL](#URL)|true| |Location of GeoPackage on remote HTTP(S) URL. GeoPackage will be downloaded to local disk
during startup and stored at the location specified in "file".| +|parallelism|[int](#int)|false|4|ADVANCED SETTING. Determines how many workers (goroutines) in parallel will download the specified GeoPackage.
Setting this to 1 will disable concurrent downloads.
+kubebuilder:default=4
+kubebuilder:validation:Minimum=1
+optional.| +|tlsSkipVerify|[bool](#bool)|false|false|ADVANCED SETTING. When true TLS certs are NOT validated, false otherwise. Only use true for your own self-signed certificates!
+kubebuilder:default=false
+optional.| +|timeout|[Duration](#Duration)|false|2m|ADVANCED SETTING. HTTP request timeout when downloading (part of) GeoPackage.
+kubebuilder:default="2m"
+optional.| +|retryDelay|[Duration](#Duration)|false|1s|ADVANCED SETTING. Minimum delay to use when retrying HTTP request to download (part of) GeoPackage.
+kubebuilder:default="1s"
+optional.| +|retryMaxDelay|[Duration](#Duration)|false|30s|ADVANCED SETTING. Maximum overall delay of the exponential backoff while retrying HTTP requests to download (part of) GeoPackage.
+kubebuilder:default="30s"
+optional.| +|maxRetries|[int](#int)|false|5|ADVANCED SETTING. Maximum number of retries when retrying HTTP requests to download (part of) GeoPackage.
+kubebuilder:default=5
+kubebuilder:validation:Minimum=1
+optional.| + +## GeoPackageCloudCache ++kubebuilder:object:generate=true. + +| Key | Type | Require | Default | Describe | +|----------|----------|-----|------------------|--------------| +|path|[string](#string)|false| |Optional path to directory for caching cloud-backed GeoPackage blocks, when omitted a temp dir will be used.
+optional.| +|maxSize|[string](#string)|false|1Gb|Max size of the local cache. Accepts human-readable size such as 100Mb, 4Gb, 1Tb, etc. When omitted 1Gb is used.
+kubebuilder:default="1Gb"
+optional.| +|warmUp|[bool](#bool)|false|false|When true a warm-up query is executed on startup which aims to fill the local cache. Does increase startup time.
+kubebuilder:default=false
+optional.| + +--- +**github.com/PDOK/gokoala/config.Config** +GENERATED BY THE COMMAND [type2md](https://github.com/eleztian/type2md) diff --git a/hack/generate-config-docs.sh b/hack/generate-config-docs.sh new file mode 100755 index 00000000..4009d39c --- /dev/null +++ b/hack/generate-config-docs.sh @@ -0,0 +1,20 @@ +#!/bin/bash + +set -o errexit +set -o nounset +set -o pipefail + +GOKOALA_ROOT=$(dirname "${BASH_SOURCE[0]}")/.. +cd "${GOKOALA_ROOT}" + +if ! command -v type2md &> /dev/null +then + echo "installing type2md" + # using fork: https://github.com/rkettelerij/type2md/tree/fork maybe permanently but at least + # until PRs https://github.com/eleztian/type2md/pull/1 and https://github.com/eleztian/type2md/pull/2 are merged + go get github.com/rkettelerij/type2md@c111a3b53690f56f658c742bda79448ed0b398e6 + go install github.com/rkettelerij/type2md@c111a3b53690f56f658c742bda79448ed0b398e6 +fi + +echo "generating markdown configuration reference from config structs" +type2md -t "Configuration Reference" -f docs/README.md github.com/PDOK/gokoala/config Config \ No newline at end of file