From 05dfebd7e4bdfd2b80d7785db12b5489964a0f99 Mon Sep 17 00:00:00 2001 From: Tom Kralidis Date: Wed, 8 Dec 2021 21:59:26 -0500 Subject: [PATCH] fix list formatting in docs --- docs/source/administration.rst | 6 +- docs/source/configuration.rst | 1 + docs/source/cql.rst | 12 ++-- .../data-publishing/ogcapi-coverages.rst | 32 ++++----- docs/source/data-publishing/ogcapi-edr.rst | 20 +++--- .../data-publishing/ogcapi-features.rst | 52 +++++++-------- .../data-publishing/ogcapi-processes.rst | 32 ++++----- .../source/data-publishing/ogcapi-records.rst | 50 +++++++------- docs/source/data-publishing/ogcapi-tiles.rst | 24 +++---- docs/source/data-publishing/stac.rst | 4 +- docs/source/further-reading.rst | 4 +- docs/source/introduction.rst | 66 +++++++++---------- docs/source/language.rst | 32 ++++----- 13 files changed, 168 insertions(+), 167 deletions(-) diff --git a/docs/source/administration.rst b/docs/source/administration.rst index ce00e03..0089eae 100644 --- a/docs/source/administration.rst +++ b/docs/source/administration.rst @@ -6,9 +6,9 @@ Administration Now that you have pygeoapi installed and a basic configuration setup, it's time to complete the administrative steps required before starting up the server. The remaining steps are: -- create OpenAPI document -- validate OpenAPI document -- set system environment variables +* create OpenAPI document +* validate OpenAPI document +* set system environment variables Creating the OpenAPI document ----------------------------- diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index a1ac41a..73d76d3 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -263,6 +263,7 @@ For collections, at the level of items, the default JSON-LD representation adds: The optional configuration options for collections, at the level of an item of items, are: - If ``uri_field`` is specified, JSON-LD will be updated such that the ``@id`` has the value of ``uri_field`` for each item in a collection + .. note:: While this is enough to provide valid RDF (as GeoJSON-LD), it does not allow the *properties* of your items to be unambiguously interpretable. diff --git a/docs/source/cql.rst b/docs/source/cql.rst index cf8a067..9759d09 100644 --- a/docs/source/cql.rst +++ b/docs/source/cql.rst @@ -9,9 +9,9 @@ Limitations The support to CQL is limited to `Simple CQL filter `_ and thus it allows to query with the following predicates: -- comparison predicates -- spatial predicates -- temporal predicates +* comparison predicates +* spatial predicates +* temporal predicates Formats ------- @@ -28,9 +28,9 @@ Queries The following type of queries are supported right now: -- ``between`` predicate query -- Logical ``and`` query with ``between`` and ``eq`` expression -- Spatial query with ``bbox`` +* ``between`` predicate query +* Logical ``and`` query with ``between`` and ``eq`` expression +* Spatial query with ``bbox`` Examples ^^^^^^^^ diff --git a/docs/source/data-publishing/ogcapi-coverages.rst b/docs/source/data-publishing/ogcapi-coverages.rst index c157abb..3344acf 100644 --- a/docs/source/data-publishing/ogcapi-coverages.rst +++ b/docs/source/data-publishing/ogcapi-coverages.rst @@ -84,22 +84,22 @@ The `xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data. Data access examples -------------------- -- list all collections - - http://localhost:5000/collections -- overview of dataset - - http://localhost:5000/collections/foo -- coverage rangetype - - http://localhost:5000/collections/foo/coverage/rangetype -- coverage domainset - - http://localhost:5000/collections/foo/coverage/domainset -- coverage access via CoverageJSON (default) - - http://localhost:5000/collections/foo/coverage?f=json -- coverage access via native format (as defined in ``provider.format.name``) - - http://localhost:5000/collections/foo/coverage?f=GRIB -- coverage access with comma-separated range-subset - - http://localhost:5000/collections/foo/coverage?range-subset=1,3 -- coverage access with subsetting - - http://localhost:5000/collections/foo/coverage?subset=lat(10,20)&subset=long(10,20) +* list all collections + * http://localhost:5000/collections +* overview of dataset + * http://localhost:5000/collections/foo +* coverage rangetype + * http://localhost:5000/collections/foo/coverage/rangetype +* coverage domainset + * http://localhost:5000/collections/foo/coverage/domainset +* coverage access via CoverageJSON (default) + * http://localhost:5000/collections/foo/coverage?f=json +* coverage access via native format (as defined in ``provider.format.name``) + * http://localhost:5000/collections/foo/coverage?f=GRIB +* coverage access with comma-separated range-subset + * http://localhost:5000/collections/foo/coverage?range-subset=1,3 +* coverage access with subsetting + * http://localhost:5000/collections/foo/coverage?subset=lat(10,20)&subset=long(10,20) .. _`OGC API - Coverages`: https://github.com/opengeospatial/ogcapi-coverages .. _`rasterio`: https://rasterio.readthedocs.io diff --git a/docs/source/data-publishing/ogcapi-edr.rst b/docs/source/data-publishing/ogcapi-edr.rst index 334b715..c82be5d 100644 --- a/docs/source/data-publishing/ogcapi-edr.rst +++ b/docs/source/data-publishing/ogcapi-edr.rst @@ -64,16 +64,16 @@ The `xarray-edr`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data Data access examples -------------------- -- list all collections - - http://localhost:5000/collections -- overview of dataset - - http://localhost:5000/collections/foo -- dataset position query - - http://localhost:5000/collections/foo/position?coords=POINT(-75%2045) -- dataset position query for a specific parameter - - http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST -- dataset position query for a specific parameter and time step - - http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST&datetime=2000-01-16 +* list all collections + * http://localhost:5000/collections +* overview of dataset + * http://localhost:5000/collections/foo +* dataset position query + * http://localhost:5000/collections/foo/position?coords=POINT(-75%2045) +* dataset position query for a specific parameter + * http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST +* dataset position query for a specific parameter and time step + * http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST&datetime=2000-01-16 .. _`xarray`: https://xarray.pydata.org diff --git a/docs/source/data-publishing/ogcapi-features.rst b/docs/source/data-publishing/ogcapi-features.rst index 44c23aa..dfff9da 100644 --- a/docs/source/data-publishing/ogcapi-features.rst +++ b/docs/source/data-publishing/ogcapi-features.rst @@ -76,8 +76,8 @@ Elasticsearch To publish an Elasticsearch index, the following are required in your index: -- indexes must be documents of valid GeoJSON Features -- index mappings must define the GeoJSON ``geometry`` as a ``geo_shape`` +* indexes must be documents of valid GeoJSON Features +* index mappings must define the GeoJSON ``geometry`` as a ``geo_shape`` .. code-block:: yaml @@ -245,29 +245,29 @@ are included in the docker examples for SensorThings. Data access examples -------------------- -- list all collections - - http://localhost:5000/collections -- overview of dataset - - http://localhost:5000/collections/foo -- queryables - - http://localhost:5000/collections/foo/queryables -- browse features - - http://localhost:5000/collections/foo/items -- paging - - http://localhost:5000/collections/foo/items?startIndex=10&limit=10 -- CSV outputs - - http://localhost:5000/collections/foo/items?f=csv -- query features (spatial) - - http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90 -- query features (attribute) - - http://localhost:5000/collections/foo/items?propertyname=foo -- query features (temporal) - - http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z -- query features (temporal) and sort ascending by a property (if no +/- indicated, + is assumed) - - http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=+datetime -- query features (temporal) and sort descending by a property - - http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime -- fetch a specific feature - - http://localhost:5000/collections/foo/items/123 +* list all collections + * http://localhost:5000/collections +* overview of dataset + * http://localhost:5000/collections/foo +* queryables + * http://localhost:5000/collections/foo/queryables +* browse features + * http://localhost:5000/collections/foo/items +* paging + * http://localhost:5000/collections/foo/items?startIndex=10&limit=10 +* CSV outputs + * http://localhost:5000/collections/foo/items?f=csv +* query features (spatial) + * http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90 +* query features (attribute) + * http://localhost:5000/collections/foo/items?propertyname=foo +* query features (temporal) + * http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z +* query features (temporal) and sort ascending by a property (if no +/- indicated, + is assumed) + * http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=+datetime +* query features (temporal) and sort descending by a property + * http://localhost:5000/collections/foo/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime +* fetch a specific feature + * http://localhost:5000/collections/foo/items/123 .. _`OGC API - Features`: https://www.ogc.org/standards/ogcapi-features diff --git a/docs/source/data-publishing/ogcapi-processes.rst b/docs/source/data-publishing/ogcapi-processes.rst index 1873ec8..4797828 100644 --- a/docs/source/data-publishing/ogcapi-processes.rst +++ b/docs/source/data-publishing/ogcapi-processes.rst @@ -52,26 +52,26 @@ Putting it all together To summarize how pygeoapi processes and managers work together:: -- process plugins implement the core processing / workflow functionality -- manager plugins control and manage how processes are executed +* process plugins implement the core processing / workflow functionality +* manager plugins control and manage how processes are executed Processing examples ------------------- -- list all processes - - http://localhost:5000/processes -- describe the ``hello-world`` process - - http://localhost:5000/processes/hello-world -- show all jobs for the ``hello-world`` process - - http://localhost:5000/processes/hello-world/jobs -- execute a job for the ``hello-world`` process - - ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"`` -- execute a job for the ``hello-world`` process with a raw response (default) - - ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"`` -- execute a job for the ``hello-world`` process with a response document - - ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"},\"response\":\"document\"}"`` -- execute a job for the ``hello-world`` process in asynchronous mode - - ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"mode\": \"async\", \"inputs\":{\"name\": \"hi there2\"}}"`` +* list all processes + * http://localhost:5000/processes +* describe the ``hello-world`` process + * http://localhost:5000/processes/hello-world +* show all jobs for the ``hello-world`` process + * http://localhost:5000/processes/hello-world/jobs +* execute a job for the ``hello-world`` process + * ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"`` +* execute a job for the ``hello-world`` process with a raw response (default) + * ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"}}"`` +* execute a job for the ``hello-world`` process with a response document + * ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"inputs\":{\"name\": \"hi there2\"},\"response\":\"document\"}"`` +* execute a job for the ``hello-world`` process in asynchronous mode + * ``curl -X POST "http://localhost:5000/processes/hello-world/execution" -H "Content-Type: application/json" -d "{\"mode\": \"async\", \"inputs\":{\"name\": \"hi there2\"}}"`` .. todo:: add more examples once OAProc implementation is complete diff --git a/docs/source/data-publishing/ogcapi-records.rst b/docs/source/data-publishing/ogcapi-records.rst index 66211c9..564f3c6 100644 --- a/docs/source/data-publishing/ogcapi-records.rst +++ b/docs/source/data-publishing/ogcapi-records.rst @@ -36,8 +36,8 @@ ElasticsearchCatalogue To publish an Elasticsearch index, the following are required in your index: -- indexes must be documents of valid `OGC API - Records GeoJSON Features`_ -- index mappings must define the GeoJSON ``geometry`` as a ``geo_shape`` +* indexes must be documents of valid `OGC API - Records GeoJSON Features`_ +* index mappings must define the GeoJSON ``geometry`` as a ``geo_shape`` .. code-block:: yaml @@ -57,7 +57,7 @@ TinyDBCatalogue To publish a TinyDB index, the following are required in your index: -- indexes must be documents of valid `OGC API - Records GeoJSON Features`_ +* indexes must be documents of valid `OGC API - Records GeoJSON Features`_ .. code-block:: yaml @@ -72,28 +72,28 @@ To publish a TinyDB index, the following are required in your index: Metadata search examples ------------------------ -- overview of record collection - - http://localhost:5000/collections/metadata-records -- queryables - - http://localhost:5000/collections/foo/queryables -- browse records - - http://localhost:5000/collections/foo/items -- paging - - http://localhost:5000/collections/foo/items?startIndex=10&limit=10 -- CSV outputs - - http://localhost:5000/collections/foo/items?f=csv -- query records (spatial) - - http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90 -- query records (attribute) - - http://localhost:5000/collections/foo/items?propertyname=foo -- query records (temporal) - - http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z -- query features (temporal) and sort ascending by a property (if no +/- indicated, + is assumed) - - http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=datetime -- query features (temporal) and sort descending by a property - - http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime -- fetch a specific record - - http://localhost:5000/collections/my-metadata/items/123 +* overview of record collection + * http://localhost:5000/collections/metadata-records +* queryables + * http://localhost:5000/collections/foo/queryables +* browse records + * http://localhost:5000/collections/foo/items +* paging + * http://localhost:5000/collections/foo/items?startIndex=10&limit=10 +* CSV outputs + * http://localhost:5000/collections/foo/items?f=csv +* query records (spatial) + * http://localhost:5000/collections/foo/items?bbox=-180,-90,180,90 +* query records (attribute) + * http://localhost:5000/collections/foo/items?propertyname=foo +* query records (temporal) + * http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z +* query features (temporal) and sort ascending by a property (if no +/- indicated, + is assumed) + * http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=datetime +* query features (temporal) and sort descending by a property + * http://localhost:5000/collections/my-metadata/items?datetime=2020-04-10T14:11:00Z&sortby=-datetime +* fetch a specific record + * http://localhost:5000/collections/my-metadata/items/123 .. _`OGC API - Records`: https://www.ogc.org/standards/ogcapi-records .. _`OGC API - Records GeoJSON Features`: https://raw.githubusercontent.com/opengeospatial/ogcapi-records/master/core/openapi/schemas/recordGeoJSON.yaml diff --git a/docs/source/data-publishing/ogcapi-tiles.rst b/docs/source/data-publishing/ogcapi-tiles.rst index 1c3a9aa..25df29a 100644 --- a/docs/source/data-publishing/ogcapi-tiles.rst +++ b/docs/source/data-publishing/ogcapi-tiles.rst @@ -11,8 +11,8 @@ object storage). To integrate tiles from a local data source, it is assumed that a directory tree of static tiles has been created on disk. Examples of tile generation software include (but are not limited to): -- `MapProxy`_ -- `tippecanoe`_ +* `MapProxy`_ +* `tippecanoe`_ Providers --------- @@ -58,16 +58,16 @@ The MVT provider plugin provides access to `Mapbox Vector Tiles`_. Data access examples -------------------- -- list all collections - - http://localhost:5000/collections -- overview of dataset - - http://localhost:5000/collections/foo -- overview of dataset tiles - - http://localhost:5000/collections/foo/tiles -- tile matrix metadata - - http://localhost:5000/collections/lakes/tiles/WorldCRS84Quad/metadata -- tiles URI template - - `http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt `_ +* list all collections + * http://localhost:5000/collections +* overview of dataset + * http://localhost:5000/collections/foo +* overview of dataset tiles + * http://localhost:5000/collections/foo/tiles +* tile matrix metadata + * http://localhost:5000/collections/lakes/tiles/WorldCRS84Quad/metadata +* tiles URI template + * `http://localhost:5000/collections/lakes/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt `_ .. _`OGC API - Tiles`: https://github.com/opengeospatial/ogcapi-tiles diff --git a/docs/source/data-publishing/stac.rst b/docs/source/data-publishing/stac.rst index 3aa6e91..19a1df7 100644 --- a/docs/source/data-publishing/stac.rst +++ b/docs/source/data-publishing/stac.rst @@ -51,8 +51,8 @@ ESRI Shapefile publishing requires to specify all required component file extens Data access examples -------------------- -- STAC root page - - http://localhost:5000/stac +* STAC root page + * http://localhost:5000/stac From here, browse the filesystem accordingly. diff --git a/docs/source/further-reading.rst b/docs/source/further-reading.rst index 2c46a99..f288573 100644 --- a/docs/source/further-reading.rst +++ b/docs/source/further-reading.rst @@ -5,5 +5,5 @@ Further Reading The following list provides information on pygeoapi and OGC API efforts. -- `Default pygeoapi presentation `_ -- `OGC API `_ +* `Default pygeoapi presentation `_ +* `OGC API `_ diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 9d07c22..a248e51 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -8,54 +8,54 @@ Introduction Features -------- -- out of the box modern OGC API server -- certified OGC Compliant and Reference Implementation for OGC API - Features -- additionally implements - - OGC API - Coverages - - OGC API - Tiles - - OGC API - Processes - - OGC API - Environmental Data Retrieval - - SpatioTemporal Asset Library -- out of the box data provider plugins for rasterio, GDAL/OGR, Elasticsearch, PostgreSQL/PostGIS -- easy to use OpenAPI / Swagger documentation for developers -- supports JSON, GeoJSON, HTML and CSV output -- supports data filtering by spatial, temporal or attribute queries -- easy to install: install a full implementation via ``pip`` or ``git`` -- simple YAML configuration -- easy to deploy: via UbuntuGIS or the official Docker image -- flexible: built on a robust plugin framework to build custom data connections, formats and processes -- supports any Python web framework (included are Flask [default], Starlette) -- supports asynchronous processing and job management (OGC API - Processes) +* out of the box modern OGC API server +* certified OGC Compliant and Reference Implementation for OGC API - Features +* additionally implements + * OGC API - Coverages + * OGC API - Tiles + * OGC API - Processes + * OGC API - Environmental Data Retrieval + * SpatioTemporal Asset Library +* out of the box data provider plugins for rasterio, GDAL/OGR, Elasticsearch, PostgreSQL/PostGIS +* easy to use OpenAPI / Swagger documentation for developers +* supports JSON, GeoJSON, HTML and CSV output +* supports data filtering by spatial, temporal or attribute queries +* easy to install: install a full implementation via ``pip`` or ``git`` +* simple YAML configuration +* easy to deploy: via UbuntuGIS or the official Docker image +* flexible: built on a robust plugin framework to build custom data connections, formats and processes +* supports any Python web framework (included are Flask [default], Starlette) +* supports asynchronous processing and job management (OGC API - Processes) Standards Support ----------------- Standards are at the core of pygeoapi. Below is the project's standards support matrix. -- Implementing: implements standard (good) -- Compliant: conforms to OGC compliance requirements (great) -- Reference Implementation: provides a reference for the standard (awesome!) +* Implementing: implements standard (good) +* Compliant: conforms to OGC compliance requirements (great) +* Reference Implementation: provides a reference for the standard (awesome!) .. csv-table:: :header: "Standard", "Support" :align: left :widths: 20, 20 - `OGC API - Features`_,Reference Implementation - `OGC API - Coverages`_,Implementing - `OGC API - Tiles`_,Implementing - `OGC API - Processes`_,Implementing - `OGC API - Records`_,Implementing - `OGC API - Environmental Data Retrieval`_,Implementing + `OGC API * Features`_,Reference Implementation + `OGC API * Coverages`_,Implementing + `OGC API * Tiles`_,Implementing + `OGC API * Processes`_,Implementing + `OGC API * Records`_,Implementing + `OGC API * Environmental Data Retrieval`_,Implementing `SpatioTemporal Asset Catalog`_,Implementing .. _`pygeoapi`: https://pygeoapi.io .. _`OGC API`: https://ogcapi.ogc.org -.. _`OGC API - Features`: https://www.ogc.org/standards/ogcapi-features -.. _`OGC API - Coverages`: https://github.com/opengeospatial/ogcapi-coverages -.. _`OGC API - Tiles`: https://github.com/opengeospatial/ogcapi-tiles -.. _`OGC API - Processes`: https://github.com/opengeospatial/ogcapi-processes -.. _`OGC API - Records`: https://github.com/opengeospatial/ogcapi-records -.. _`OGC API - Environmental Data Retrieval`: https://github.com/opengeospatial/ogcapi-environmental-data-retrieval +.. _`OGC API * Features`: https://www.ogc.org/standards/ogcapi-features +.. _`OGC API * Coverages`: https://github.com/opengeospatial/ogcapi-coverages +.. _`OGC API * Tiles`: https://github.com/opengeospatial/ogcapi-tiles +.. _`OGC API * Processes`: https://github.com/opengeospatial/ogcapi-processes +.. _`OGC API * Records`: https://github.com/opengeospatial/ogcapi-records +.. _`OGC API * Environmental Data Retrieval`: https://github.com/opengeospatial/ogcapi-environmental-data-retrieval .. _`SpatioTemporal Asset Catalog`: https://stacspec.org diff --git a/docs/source/language.rst b/docs/source/language.rst index 1e7d5d9..f2a8653 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -36,27 +36,27 @@ There are 2 ways to affect the language of the results returned by pygeoapi, bot Notes ^^^^^ -- If pygeoapi cannot find a good match to the requested language, the response is returned in the default language (US English mostly). +* If pygeoapi cannot find a good match to the requested language, the response is returned in the default language (US English mostly). The default language is the *first* language defined in pygeoapi's server configuration YAML (see `maintainer guide`_). -- Even if pygeoapi *itself* supports the requested language, provider plugins may not support that particular language or perhaps don't even +* Even if pygeoapi *itself* supports the requested language, provider plugins may not support that particular language or perhaps don't even support any language at all. In that case the provider will reply in its own "unknown" language, which may not be the same language as the default pygeoapi server language set in the ``Content-Language`` HTTP response header. -- It is up to the creator of the provider to properly define at least 1 supported language in the provider configuration, as described +* It is up to the creator of the provider to properly define at least 1 supported language in the provider configuration, as described in the `developer guide`_. This will ensure that the ``Content-Language`` HTTP response header is always set properly. -- If pygeoapi found a match to the requested language, the response will include a ``Content-Language`` HTTP header, +* If pygeoapi found a match to the requested language, the response will include a ``Content-Language`` HTTP header, set to the best-matching server language code. This is the default behavior for most pygeoapi requests. However, note that some responses (e.g. exceptions) always have a ``Content-Language: en-US`` header, regardless of the requested language. -- For results returned by a **provider**, the ``Content-Language`` HTTP header will be set to the best-matching +* For results returned by a **provider**, the ``Content-Language`` HTTP header will be set to the best-matching provider language or the best-matching pygeoapi server language if the provider is not language-aware. -- If the provider supports a requested language, but pygeoapi does *not* support that same language, the ``Content-Language`` +* If the provider supports a requested language, but pygeoapi does *not* support that same language, the ``Content-Language`` header will contain both the provider language *and* the best-matching pygeoapi server language. -- Please note that the ``Content-Language`` HTTP response header only *indicates the language of the intended audience*. +* Please note that the ``Content-Language`` HTTP response header only *indicates the language of the intended audience*. It does not necessarily mean that the content is actually written in that particular language. @@ -94,14 +94,14 @@ Next, you will have to provide translations for the configured languages. This i Notes ^^^^^ -- The **first** language you define in the configuration determines the default language, i.e. the language that pygeoapi will +* The **first** language you define in the configuration determines the default language, i.e. the language that pygeoapi will use if no other language was requested or no best match for the requested language could be found. -- It is not possible to **disable** language support in pygeoapi. The functionality is always on and a ``Content-Language`` +* It is not possible to **disable** language support in pygeoapi. The functionality is always on and a ``Content-Language`` HTTP response header is always set. If results should be available in a single language, you'd have to set that language only in the pygeoapi configuration. -- Results returned from a provider may be in a different language than pygeoapi's own server language. The "raw" requested language +* Results returned from a provider may be in a different language than pygeoapi's own server language. The "raw" requested language is always passed on to the provider, even if pygeoapi itself does not support it. For more information, see the `end user guide`_ and the `developer guide`_. @@ -248,20 +248,20 @@ This is all that is required. The pygeoapi API class will make sure that the cor Notes ^^^^^ -- If your provider implements any of the aforementioned ``query``, ``get`` and ``get_metadata`` methods, +* If your provider implements any of the aforementioned ``query``, ``get`` and ``get_metadata`` methods, it **must** add a ``**kwargs`` or ``language=None`` parameter, even if it does not need to use the language parameter. -- Contrary to the pygeoapi server configuration, adding a ``language`` or ``languages`` (both are supported) property to the +* Contrary to the pygeoapi server configuration, adding a ``language`` or ``languages`` (both are supported) property to the provider definition is **not** required and may be omitted. In that case, the passed-in ``language`` parameter language-aware provider methods (``query``, ``get``, etc.) will be set to ``None``. This results in the following behavior: - - HTML responses returned from the providers will have the ``Content-Language`` header set to the best-matching pygeoapi server language. - - JSON(-LD) responses returned from providers will **not** have a ``Content-Language`` header if ``language`` is ``None``. + * HTML responses returned from the providers will have the ``Content-Language`` header set to the best-matching pygeoapi server language. + * JSON(-LD) responses returned from providers will **not** have a ``Content-Language`` header if ``language`` is ``None``. -- If the provider supports a requested language, the passed-in ``language`` will be set to the best matching +* If the provider supports a requested language, the passed-in ``language`` will be set to the best matching `Babel Locale instance `_. Note that this may be the provider default language if no proper match was found. No matter the output format, API responses returned from providers will always contain a best-matching ``Content-Language`` header if one ore more supported provider languages were defined. -- For general information about building plugins, please visit the :ref:`plugins` page. +* For general information about building plugins, please visit the :ref:`plugins` page.