From a15f9f2b52cb9f40c93490d6ea8beb029fa3744b Mon Sep 17 00:00:00 2001 From: Tom Kralidis Date: Fri, 3 Feb 2023 20:50:21 -0500 Subject: [PATCH] add note for running WSGI and a virtualenv (thanks Australia BOM) (#1131) * add note for running WSGI and a virtualenv (thanks Australia BOM) * docs sweep * fix --- docs/source/_templates/indexsidebar.html | 16 ++++++------ docs/source/conf.py | 2 +- docs/source/configuration.rst | 4 +-- .../data-publishing/ogcapi-coverages.rst | 26 +++++++++++-------- docs/source/data-publishing/ogcapi-edr.rst | 4 +-- .../data-publishing/ogcapi-features.rst | 22 ++++++++-------- docs/source/data-publishing/ogcapi-maps.rst | 6 ++--- .../data-publishing/ogcapi-processes.rst | 4 +-- .../source/data-publishing/ogcapi-records.rst | 6 ++--- docs/source/data-publishing/ogcapi-tiles.rst | 4 +-- docs/source/development.rst | 8 +++--- docs/source/installation.rst | 10 +++---- docs/source/language.rst | 2 +- docs/source/openapi.rst | 4 +-- docs/source/plugins.rst | 6 ++--- docs/source/running.rst | 21 ++++++++++----- docs/source/transactions.rst | 2 +- 17 files changed, 80 insertions(+), 67 deletions(-) diff --git a/docs/source/_templates/indexsidebar.html b/docs/source/_templates/indexsidebar.html index 0546ab5..79b9eff 100644 --- a/docs/source/_templates/indexsidebar.html +++ b/docs/source/_templates/indexsidebar.html @@ -4,20 +4,20 @@ pygeoapi logo

- - Certified OGC Compliant + + Certified OGC Compliant - - OGC Reference Implementation + + OGC Reference Implementation - - OGC Reference Implementation + + OGC Reference Implementation OSGeo Project - - FOSS4G Conference + + FOSS4G Conference

diff --git a/docs/source/conf.py b/docs/source/conf.py index f1ca952..2809373 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -152,7 +152,7 @@ html_static_path = ['_static'] # to template names. # # This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +# refs: https://alabaster.readthedocs.io/en/latest/installation.html#sidebars html_sidebars = { '**': [ 'relations.html', # needs 'show_related': True theme option to display diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 7a469d7..8120ad9 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -53,7 +53,7 @@ The ``server`` section provides directives on binding and high level tuning. map: # leaflet map setup for HTML pages url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png attribution: 'Wikimedia maps | Map data © OpenStreetMap contributors' - ogc_schemas_location: /opt/schemas.opengis.net # local copy of http://schemas.opengis.net + ogc_schemas_location: /opt/schemas.opengis.net # local copy of https://schemas.opengis.net manager: # optional OGC API - Processes asynchronous job management name: TinyDB # plugin name (see pygeoapi.plugin for supported process_manager's) @@ -447,4 +447,4 @@ At this point, you have the configuration ready to administer the server. .. _`YAML`: https://en.wikipedia.org/wiki/YAML .. _`JSON-LD`: https://json-ld.org .. _`Google Structured Data Testing Tool`: https://search.google.com/structured-data/testing-tool#url=https%3A%2F%2Fdemo.pygeoapi.io%2Fmaster -.. _`Google Dataset Search`: https://developers.google.com/search/docs/data-types/dataset +.. _`Google Dataset Search`: https://developers.google.com/search/docs/appearance/structured-data/dataset diff --git a/docs/source/data-publishing/ogcapi-coverages.rst b/docs/source/data-publishing/ogcapi-coverages.rst index aae1aa0..fa839b3 100644 --- a/docs/source/data-publishing/ogcapi-coverages.rst +++ b/docs/source/data-publishing/ogcapi-coverages.rst @@ -18,8 +18,8 @@ parameters. :header: Provider, properties, subset, bbox, datetime :align: left - rasterio,✅,✅,✅, - xarray,✅,✅,✅,✅ + :ref:`Rasterio`,✅,✅,✅, + :ref:`Xarray`,✅,✅,✅,✅ Below are specific connection examples based on supported providers. @@ -27,13 +27,15 @@ Below are specific connection examples based on supported providers. Connection examples ------------------- -rasterio +.. _rasterio-provider: + +Rasterio ^^^^^^^^ .. note:: - Requires Python package rasterio + Requires Python package Rasterio -The `rasterio`_ provider plugin reads and extracts any data that rasterio is +The `Rasterio`_ provider plugin reads and extracts any data that Rasterio is capable of handling. .. code-block:: yaml @@ -49,16 +51,18 @@ capable of handling. mimetype: application/x-grib2 .. note:: - The rasterio provider ``format.name`` directive **requires** a valid + The Rasterio provider ``format.name`` directive **requires** a valid `GDAL raster driver short name`_. +.. _xarray-provider: + xarray ^^^^^^ .. note:: - Requires Python package xarray + Requires Python package Xarray -The `xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data. +The `Xarray`_ provider plugin reads and extracts `NetCDF`_ and `Zarr`_ data. .. code-block:: yaml @@ -105,7 +109,7 @@ Data access examples * coverage access with comma-separated properties * http://localhost:5000/collections/foo/coverage?properties=1,3 * coverage access with subsetting - * http://localhost:5000/collections/foo/coverage?subset=lat(10,20)&subset=long(10,20) + * http://localhost:5000/collections/foo/coverage?subset=lat(10:20)&subset=long(10:20) * coverage with bbox * http://localhost:5000/collections/foo/coverage?bbox=10,10,20,20 * coverage with bbox and bbox CRS @@ -116,8 +120,8 @@ Data access examples will have the response filename matching the collection name and appropriate file extension (e.g. ``my-dataset.nc``) .. _`OGC API - Coverages`: https://github.com/opengeospatial/ogcapi-coverages -.. _`rasterio`: https://rasterio.readthedocs.io -.. _`xarray`: https://xarray.pydata.org +.. _`Rasterio`: https://rasterio.readthedocs.io +.. _`Xarray`: https://docs.xarray.dev/en/stable .. _`NetCDF`: https://en.wikipedia.org/wiki/NetCDF .. _`Zarr`: https://zarr.readthedocs.io/en/stable .. _`GDAL raster driver short name`: https://gdal.org/drivers/raster/index.html diff --git a/docs/source/data-publishing/ogcapi-edr.rst b/docs/source/data-publishing/ogcapi-edr.rst index 4154691..9979d7c 100644 --- a/docs/source/data-publishing/ogcapi-edr.rst +++ b/docs/source/data-publishing/ogcapi-edr.rst @@ -20,7 +20,7 @@ parameters. :header: Provider, coords, parameter-name, datetime :align: left - xarray-edr,✅,✅,✅ + `xarray-edr`_,✅,✅,✅ Below are specific connection examples based on supported providers. @@ -79,7 +79,7 @@ Data access examples * http://localhost:5000/collections/foo/position?coords=POINT(-75%2045)¶meter-name=SST&datetime=2000-01-16 -.. _`xarray`: https://xarray.pydata.org +.. _`xarray`: https://docs.xarray.dev/en/stable/ .. _`NetCDF`: https://en.wikipedia.org/wiki/NetCDF .. _`Zarr`: https://zarr.readthedocs.io/en/stable diff --git a/docs/source/data-publishing/ogcapi-features.rst b/docs/source/data-publishing/ogcapi-features.rst index b5b68ea..08b0c70 100644 --- a/docs/source/data-publishing/ogcapi-features.rst +++ b/docs/source/data-publishing/ogcapi-features.rst @@ -18,16 +18,16 @@ parameters. :header: Provider, property filters/display, resulttype, bbox, datetime, sortby, skipGeometry, CQL, transactions :align: left - CSV,✅/✅,results/hits,❌,❌,❌,✅,❌,❌ - Elasticsearch,✅/✅,results/hits,✅,✅,✅,✅,✅,✅ - ESRIFeatureService,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ - GeoJSON,✅/✅,results/hits,❌,❌,❌,✅,❌,❌ - MongoDB,✅/❌,results,✅,✅,✅,✅,❌,❌ - OGR,✅/❌,results/hits,✅,❌,❌,✅,❌,❌ - PostgreSQL,✅/✅,results/hits,✅,✅,✅,✅,✅,❌ - SQLiteGPKG,✅/❌,results/hits,✅,❌,❌,✅,❌,❌ - SensorThingsAPI,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ - Socrata,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ + `CSV`_,✅/✅,results/hits,❌,❌,❌,✅,❌,❌ + `Elasticsearch`_,✅/✅,results/hits,✅,✅,✅,✅,✅,✅ + `ESRI Feature Service`_,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ + `GeoJSON`_,✅/✅,results/hits,❌,❌,❌,✅,❌,❌ + `MongoDB`_,✅/❌,results,✅,✅,✅,✅,❌,❌ + `OGR`_,✅/❌,results/hits,✅,❌,❌,✅,❌,❌ + `PostgreSQL`_,✅/✅,results/hits,✅,✅,✅,✅,✅,❌ + `SQLiteGPKG`_,✅/❌,results/hits,✅,❌,❌,✅,❌,❌ + `SensorThings API`_,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ + `Socrata`_,✅/✅,results/hits,✅,✅,✅,✅,❌,❌ Below are specific connection examples based on supported providers. @@ -287,7 +287,7 @@ SensorThings API The STA provider is capable of creating feature collections from OGC SensorThings API endpoints. Three of the STA entities are configurable: Things, Datastreams, and Observations. For a full description of the SensorThings entity model, see -`here `_. +`here `_. For each entity of ``Things``, pygeoapi will expand all entities directly related to the ``Thing``, including its associated ``Location``, from which the geometry for the feature collection is derived. Similarly, ``Datastreams`` are expanded to diff --git a/docs/source/data-publishing/ogcapi-maps.rst b/docs/source/data-publishing/ogcapi-maps.rst index 68f061d..08a340f 100644 --- a/docs/source/data-publishing/ogcapi-maps.rst +++ b/docs/source/data-publishing/ogcapi-maps.rst @@ -18,8 +18,8 @@ parameters. :header: Provider, bbox, width/height :align: left - MapScript,,✅,✅ - WMSFacade,,✅,✅ + `MapScript`,,✅,✅ + `WMSFacade`_,,✅,✅ Below are specific connection examples based on supported providers. @@ -98,5 +98,5 @@ Data visualization examples * map with bbox and bbox-crs * http://localhost:5000/collections/foo/map?bbox-crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3857&bbox=4.022369384765626%2C50.690447870569436%2C4.681549072265626%2C51.00260125274477&width=800&height=600&transparent -.. _`OGC API - Maps`: https://www.ogc.org/standards/ogcapi-maps +.. _`OGC API - Maps`: https://ogcapi.ogc.org/maps .. _`MapScript`: https://mapserver.org/mapscript/index.html diff --git a/docs/source/data-publishing/ogcapi-processes.rst b/docs/source/data-publishing/ogcapi-processes.rst index 1fd3afa..52e5b82 100644 --- a/docs/source/data-publishing/ogcapi-processes.rst +++ b/docs/source/data-publishing/ogcapi-processes.rst @@ -75,6 +75,6 @@ Processing examples .. todo:: add more examples once OAProc implementation is complete -.. _`OGC API - Processes`: https://github.com/opengeospatial/ogcapi-processes +.. _`OGC API - Processes`: https://ogcapi.ogc.org/processes .. _`sample`: https://github.com/geopython/pygeoapi/blob/master/pygeoapi/process/hello_world.py -.. _`TinyDB`: https://tinydb.readthedocs.io +.. _`TinyDB`: https://tinydb.readthedocs.io/en/latest diff --git a/docs/source/data-publishing/ogcapi-records.rst b/docs/source/data-publishing/ogcapi-records.rst index 3d7c4ef..eb03173 100644 --- a/docs/source/data-publishing/ogcapi-records.rst +++ b/docs/source/data-publishing/ogcapi-records.rst @@ -18,8 +18,8 @@ parameters. :header: Provider, properties (filters), resulttype, q, bbox, datetime, sortby, properties (display), transactions :align: left - ElasticsearchCatalogue,✅,results/hits,✅,✅,✅,✅,❌ - TinyDBCatalogue,✅,results/hits,✅,✅,✅,✅,✅ + `ElasticsearchCatalogue`_,✅,results/hits,✅,✅,✅,✅,❌ + `TinyDBCatalogue`_,✅,results/hits,✅,✅,✅,✅,✅ Below are specific connection examples based on supported providers. @@ -101,5 +101,5 @@ Metadata search examples provider `id_field` values support slashes (i.e. ``my/cool/identifier``). The client request would then be responsible for encoding the identifier accordingly (i.e. ``http://localhost:5000/collections/my-metadata/items/my%2Fcool%2Fidentifier``) -.. _`OGC API - Records`: https://www.ogc.org/standards/ogcapi-records +.. _`OGC API - Records`: https://ogcapi.ogc.org/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 3c93749..ab9eb8c 100644 --- a/docs/source/data-publishing/ogcapi-tiles.rst +++ b/docs/source/data-publishing/ogcapi-tiles.rst @@ -23,7 +23,7 @@ pygeoapi core tile providers are listed below, along with supported storage type :header: Provider, local, remote :align: left - MVT,✅,✅ + `MVT`_,✅,✅ Below are specific connection examples based on supported providers. @@ -121,4 +121,4 @@ Data access examples .. _`OGC API - Tiles`: https://github.com/opengeospatial/ogcapi-tiles .. _`MapProxy`: https://mapproxy.org .. _`tippecanoe`: https://github.com/mapbox/tippecanoe -.. _`Mapbox Vector Tiles`: https://docs.mapbox.com/vector-tiles/reference +.. _`Mapbox Vector Tiles`: https://docs.mapbox.com/data/tilesets/guides/vector-tiles-introduction/ diff --git a/docs/source/development.rst b/docs/source/development.rst index 945eff8..ed4a6e1 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -36,12 +36,12 @@ Schema The Common Query Language (CQL) is the part 3 of the standard OGC API - Features. This extension has its specification available at `OGC API - Features - Part 3: Filtering and the Common Query Language (CQL) `_ and the schema exists in development at -`cql.json `_. +`cql.json `_. Model generation ^^^^^^^^^^^^^^^^ -pygeoapi uses a class-based python model interface to translate the schema into python objects defined by `pydantic `_ models. +pygeoapi uses a class-based Python model interface to translate the schema into Python objects defined by `pydantic `_ models. The model is generated with the pre-processing of the schema through the utility ``datamodel-codegen``: .. code-block:: bash @@ -52,7 +52,7 @@ The model is generated with the pre-processing of the schema through the utility How to merge ^^^^^^^^^^^^ -Once the new pydantic models have been generated then the content of the python file ``cql_update.py`` can be used to replace the old classes within the ``cql.py`` file. +Once the new pydantic models have been generated then the content of the Python file ``cql_update.py`` can be used to replace the old classes within the ``cql.py`` file. Update everything above the function ``get_next_node`` and then verify if the tests for the CQL are still passing, for example ``test_post_cql_json_between_query`` in ``tests/test_elasticsearch__provider.py``. @@ -74,7 +74,7 @@ Make Homebrew and pyenv play nicely together: alias brew='env PATH=${PATH//$(pyenv root)\/shims:/} brew' -Install python with the option to enable SQLite extensions: +Install Python with the option to enable SQLite extensions: .. code-block:: bash diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 23f3af1..c3ff21b 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -20,14 +20,14 @@ For developers and the truly impatient .. code-block:: bash - python -m venv pygeoapi + python3 -m venv pygeoapi cd pygeoapi . bin/activate git clone https://github.com/geopython/pygeoapi.git cd pygeoapi - pip install --upgrade pip - pip install -r requirements.txt - python setup.py install + pip3 install --upgrade pip + pip3 install -r requirements.txt + python3 setup.py install cp pygeoapi-config.yml example-config.yml vi example-config.yml # edit as required export PYGEOAPI_CONFIG=example-config.yml @@ -44,7 +44,7 @@ pip .. code-block:: bash - pip install pygeoapi + pip3 install pygeoapi Docker ------ diff --git a/docs/source/language.rst b/docs/source/language.rst index 7b4bc0e..7eafb80 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -273,7 +273,7 @@ Notes * 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 - `Babel Locale instance `_. + `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. diff --git a/docs/source/openapi.rst b/docs/source/openapi.rst index 0c387b8..1d35933 100644 --- a/docs/source/openapi.rst +++ b/docs/source/openapi.rst @@ -9,7 +9,7 @@ endpoints. OGC API specifications leverage OpenAPI to describe the API in great The RESTful structure and payload are defined using JSON or YAML file structures (pygeoapi uses YAML). The basic structure is described here: ``_ -The official OpenAPI specification can be found `on GitHub `_. +The official OpenAPI specification can be found `on GitHub `_. pygeoapi supports OpenAPI version 3.0.2. As described in :ref:`administration`, the pygeoapi OpenAPI document is automatically generated based on the @@ -65,7 +65,7 @@ This identifier can be used to obtain a specific item from the dataset using the Using OpenAPI via ReDoc ----------------------- -pygeoapi also supports OpenAPI document rendering via `ReDoc `_. +pygeoapi also supports OpenAPI document rendering via `ReDoc `_. ReDoc rendering is accessible at the same ``/openapi`` endpoint, adding ``ui=redoc`` to the request URL. diff --git a/docs/source/plugins.rst b/docs/source/plugins.rst index b4c03d6..03b3fe0 100644 --- a/docs/source/plugins.rst +++ b/docs/source/plugins.rst @@ -133,7 +133,7 @@ The following methods are options to connect the plugin to pygeoapi: **Option 2**: implement outside of pygeoapi and add to configuration (recommended) * create a Python package of the ``mycoolvectordata.py`` module (see `Cookiecutter`_ as an example) -* install your Python package onto your system (``python setup.py install``). At this point your new package +* install your Python package onto your system (``python3 setup.py install``). At this point your new package should be in the ``PYTHONPATH`` of your pygeoapi installation * specify in your dataset provider configuration as follows: @@ -261,11 +261,11 @@ by downstream applications. `pygeometa-plugin`_,pygeometa project,pygeometa as a service -.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter-pypackage +.. _`Cookiecutter`: https://github.com/audreyfeldroy/cookiecutter-pypackage .. _`msc-pygeoapi`: https://github.com/ECCC-MSC/msc-pygeoapi .. _`pygeoapi-kubernetes-papermill`: https://github.com/eurodatacube/pygeoapi-kubernetes-papermill .. _`local-outlier-factor-plugin`: https://github.com/manaakiwhenua/local-outlier-factor-plugin .. _`ogc-edc`: https://github.com/eurodatacube/ogc-edc/tree/oapi/edc_ogc/pygeoapi -.. _`nldi_xstool`: https://github.com/ACWI-SSWD/nldi_xstool +.. _`nldi_xstool`: https://code.usgs.gov/wma/nhgf/toolsteam/nldi-xstool .. _`pygeoapi-plugin-cookiecutter`: https://code.usgs.gov/wma/nhgf/pygeoapi-plugin-cookiecutter .. _`pygeometa-plugin`: https://geopython.github.io/pygeometa/pygeoapi-plugin diff --git a/docs/source/running.rst b/docs/source/running.rst index cbdd87b..93711fc 100644 --- a/docs/source/running.rst +++ b/docs/source/running.rst @@ -136,6 +136,15 @@ Now configure in Apache: Header set Access-Control-Allow-Origin "*" + +When running pygeoapi in a Python virtual environment, use directives similar to the below: + +.. code-block:: apache + + WSGIDaemonProcess pygeoapi processes=1 threads=1 python-home=/path/to/venv/pygeoapi + WSGIScriptAlias /pygeoapi /path/to/pygeoapi.wsgi process-group=pygeoapi application-group=%{RESOURCE} + + Gunicorn ^^^^^^^^ @@ -146,7 +155,7 @@ Gunicorn HTTP request --> WSGI or ASGI server (gunicorn) <--> Flask or Starlette (pygeoapi/flask_app.py or pygeoapi/starlette_app.py) <--> pygeoapi API .. note:: - Gunicorn is as easy to install as ``pip install gunicorn`` + Gunicorn is as easy to install as ``pip3 install gunicorn`` .. note:: For a complete list of WSGI server implementations, see the `WSGI server list`_. @@ -179,7 +188,7 @@ is simple to run from the command, e.g: gunicorn pygeoapi.starlette_app:app -w 4 -k uvicorn.workers.UvicornWorker .. note:: - Uvicorn is as easy to install as ``pip install uvicorn`` + Uvicorn is as easy to install as ``pip3 install uvicorn`` Django @@ -213,10 +222,10 @@ and modify accordingly. .. _`WSGI`: https://en.wikipedia.org/wiki/Web_Server_Gateway_Interface -.. _`ASGI`: https://asgi.readthedocs.io +.. _`ASGI`: https://asgi.readthedocs.io/en/latest .. _`Gunicorn`: https://gunicorn.org .. _`WSGI server list`: https://wsgi.readthedocs.io/en/latest/servers.html -.. _`Gunicorn settings`: http://docs.gunicorn.org/en/stable/settings.html +.. _`Gunicorn settings`: https://docs.gunicorn.org/en/stable/settings.html .. _`Uvicorn`: https://www.uvicorn.org -.. _`mod_wsgi`: https://modwsgi.readthedocs.io -.. _`Django`: https://djangoproject.com +.. _`mod_wsgi`: https://modwsgi.readthedocs.io/en/master +.. _`Django`: https://www.djangoproject.com diff --git a/docs/source/transactions.rst b/docs/source/transactions.rst index 53162a8..ac846d0 100644 --- a/docs/source/transactions.rst +++ b/docs/source/transactions.rst @@ -16,4 +16,4 @@ Access control It should be made clear that authentication and authorization is beyond the responsibility of pygeoapi. This means that if a pygeoapi user enables transactions, they must provide access control explicity via another service. -.. _`OGC API - Features - Part 4: Create, Replace, Update and Delete`: http://docs.ogc.org/DRAFTS/20-002.html +.. _`OGC API - Features - Part 4: Create, Replace, Update and Delete`: https://docs.ogc.org/DRAFTS/20-002.html