fix, docs, ci: readme, packaging, python versions

* docs: update readme

* ci: fixup packages CI

* ci: fixup doc building and python versions

* docs, fix: review suggestions

Author: gadomski

.github/workflows/cicd.yaml

@@ -46,6 +46,8 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: setup.py
 
       - name: Lint code
         if: ${{ matrix.python-version == 3.8 }}
@@ -96,7 +98,7 @@ jobs:
         with:
           python-version: "3.10"
           cache: pip
-          cache-dependency-path: setup.cfg
+          cache-dependency-path: setup.py
       - name: Install stac-fastapi and stac-api-validator
         run: pip install .[server] stac-api-validator==0.4.1
       - name: Load data and validate
@@ -118,5 +120,15 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - name: Test generating docs
+      - name: Setup Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+          cache: pip
+          cache-dependency-path: setup.py
+      - name: Install with documentation dependencies
+        run: pip install .[docs,dev,server]
+      - name: Generate API docs
         run: make docs
+      - name: Build documentation
+        run: mkdocs build --strict

.github/workflows/packages.yml

@@ -5,17 +5,14 @@ on:
       - main
     tags:
       - "*"
+  workflow_dispatch:
 
 jobs:
   docker-build-push:
     runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: write
-    strategy:
-      fail-fast: true
-      matrix:
-        backend: ["sqlalchemy", "pgstac"]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v3
@@ -29,17 +26,12 @@ jobs:
         id: meta
         uses: docker/[email protected]
         with:
-          images: ghcr.io/stac-utils/stac-fastapi
-          tags: |
-            type=schedule,suffix=-${{ matrix.backend }}
-            type=ref,event=branch,suffix=-${{ matrix.backend }}
-            type=ref,event=tag,suffix=-${{ matrix.backend }}
-            type=ref,event=pr,suffix=-${{ matrix.backend }}
+          images: ghcr.io/stac-utils/stac-fastapi-pgstac
       - name: Build and push Docker image
         uses: docker/[email protected]
         with:
           context: .
-          file: docker/Dockerfile.${{ matrix.backend }}
+          file: docker/Dockerfile
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

.github/workflows/deploy_mkdocs.yml renamed to .github/workflows/pages.yml

@@ -1,15 +1,19 @@
-name: Publish docs via GitHub Pages
+name: Deploy static content to Pages
 
 on:
   push:
     branches:
       - main
-    paths:
-      # Rebuild website when docs have changed or code has changed
-      - "README.md"
-      - "docs/**"
-      - "mkdocs.yml"
-      - "**.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -19,18 +23,18 @@ jobs:
     steps:
       - name: Checkout main
         uses: actions/checkout@v3
-
-      - name: Set up Python 3.8
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Set up Python 3.10
         uses: actions/setup-python@v4
         with:
-          python-version: 3.8
-
+          python-version: 3.10
+          cache: pip
+          cache-dependency-path: setup.py
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install -e .
-          python -m pip install mkdocs mkdocs-material pdocs
-
+          python -m pip install -e .[docs]
       - name: Update API docs
         run: |
           pdocs as_markdown \
@@ -46,6 +50,12 @@ jobs:
           POSTGRES_PORT: 5432
           POSTGRES_HOST_READER: localhost
           POSTGRES_HOST_WRITER: localhost
-
-      - name: Deploy docs
-        run: mkdocs gh-deploy --force
+      - name: Build docs
+        run: mkdocs build --site-dir site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/publish.yml

@@ -11,20 +11,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-
       - name: Set up Python 3.x
         uses: actions/setup-python@v4
         with:
           python-version: "3.x"
-
       - name: Install release dependencies
         run: |
           python -m pip install --upgrade pip
           pip install setuptools wheel twine
-
       - name: Build and publish package
         env:
           TWINE_USERNAME: ${{ secrets.PYPI_STACUTILS_USERNAME }}
           TWINE_PASSWORD: ${{ secrets.PYPI_STACUTILS_PASSWORD }}
         run: |
-          scripts/publish
+          scripts/publish

README.md

@@ -1,66 +1,90 @@
+# stac-fastapi-pgstac
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-fastapi-pgstac/cicd.yaml?style=for-the-badge)](https://github.com/stac-utils/stac-fastapi-pgstac/actions/workflows/cicd.yaml)
+[![PyPI](https://img.shields.io/pypi/v/stac-fastapi.pgstac?style=for-the-badge)](https://pypi.org/project/stac-fastapi.pgstac)
+[![Documentation](https://img.shields.io/github/actions/workflow/status/stac-utils/stac-fastapi-pgstac/pages.yml?label=Docs&style=for-the-badge)](https://stac-utils.github.io/stac-fastapi-pgstac/)
+[![License](https://img.shields.io/github/license/stac-utils/stac-fastapi-pgstac?style=for-the-badge)](https://github.com/stac-utils/stac-fastapi-pgstac/blob/main/LICENSE)
+
 <p align="center">
-  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=400>
-  <p align="center">FastAPI implemention of the STAC API spec using <a href="https://github.com/stac-utils/pgstac">PGStac</a></p>
-</p>
-<p align="center">
-  <a href="https://github.com/stac-utils/stac-fastapi/actions?query=workflow%3Acicd" target="_blank">
-      <img src="https://github.com/stac-utils/stac-fastapi/workflows/stac-fastapi/badge.svg" alt="Test">
-  </a>
-  <a href="https://pypi.org/project/stac-fastapi" target="_blank">
-      <img src="https://img.shields.io/pypi/v/stac-fastapi?color=%2334D058&label=pypi%20package" alt="Package version">
-  </a>
-  <a href="https://github.com/stac-utils/stac-fastapi/blob/main/LICENSE" target="_blank">
-      <img src="https://img.shields.io/github/license/stac-utils/stac-fastapi.svg" alt="Downloads">
-  </a>
+  <img src="https://user-images.githubusercontent.com/10407788/174893876-7a3b5b7a-95a5-48c4-9ff2-cc408f1b6af9.png" style="vertical-align: middle; max-width: 400px; max-height: 100px;" height=100 />
+  <img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI" style="vertical-align: middle; max-width: 400px; max-height: 100px;" width=200 />
 </p>
 
----
+[PgSTAC](https://github.com/stac-utils/pgstac) backend for [stac-fastapi](https://github.com/stac-utils/stac-fastapi), the [FastAPI](https://fastapi.tiangolo.com/) implementation of the [STAC API spec](https://github.com/radiantearth/stac-api-spec)
 
-**Documentation**: [https://stac-utils.github.io/stac-fastapi/](https://stac-utils.github.io/stac-fastapi/)
+## Overview
 
-**Source Code**: [https://github.com/stac-utils/stac-fastapi](https://github.com/stac-utils/stac-fastapi)
+**stac-fastapi-pgstac** is an HTTP interface built in FastAPI.
+It validates requests and data sent to a [PgSTAC](https://github.com/stac-utils/pgstac) backend, and adds [links](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#link-object) to the returned data.
+All other processing and search is provided directly using PgSTAC procedural sql / plpgsql functions on the database.
+PgSTAC stores all collection and item records as jsonb fields exactly as they come in allowing for any custom fields to be stored and retrieved transparently.
 
----
+## Usage
 
-Stac FastAPI using the [PGStac](https://github.com/stac-utils/pgstac) backend.
+PgSTAC is an external project and may be used by multiple front ends.
+For Stac FastAPI development, a Docker image (which is pulled as part of the docker-compose) is available via the [Github container registry](https://github.com/stac-utils/pgstac/pkgs/container/pgstac/81689794?tag=latest).
+The PgSTAC version required by **stac-fastapi-pgstac** is found in the [setup](http://github.com/stac-utils/stac-fastapi-pgstac/blob/main/setup.py) file.
 
-[PGStac](https://github.com/stac-utils/pgstac) is a separately managed PostgreSQL database that is designed for enhanced performance to be able to scale Stac FastAPI to be able to efficiently handle hundreds of millions of records. [PGStac](https://github.com/stac-utils/pgstac) automatically includes indexes on Item id, Collection id, Item Geometry, Item Datetime, and an Index for equality checks on any key in Item Properties. Additional indexes may be added to Item Properties to speed up the use of order, <, <=, >, and >= queries.
+### Sorting
 
-Stac FastAPI acts as the HTTP interface validating any requests and data that is sent to the [PGStac](https://github.com/stac-utils/pgstac) backend and adds in Link items on data return relative to the service host. All other processing and search is provided directly using PGStac procedural sql / plpgsql functions on the database.
+While the STAC [Sort Extension](https://github.com/stac-api-extensions/sort) is fully supported, [PgSTAC](https://github.com/stac-utils/pgstac) is particularly enhanced to be able to sort by datetime (either ascending or descending).
+Sorting by anything other than datetime (the default if no sort is specified) on very large STAC repositories without very specific query limits (ie selecting a single day date range) will not have the same performance.
+For more than millions of records it is recommended to either set a low connection timeout on PostgreSQL or to disable use of the Sort Extension.
 
-PGStac stores all collection and item records as jsonb fields exactly as they come in allowing for any custom fields to be stored and retrieved transparently.
+### Hydration
 
-While the Stac Sort Extension is fully supported, [PGStac](https://github.com/stac-utils/pgstac) is particularly enhanced to be able to sort by datetime (either ascending or descending). Sorting by anything other than datetime (the default if no sort is specified) on very large Stac repositories without very specific query limits (ie selecting a single day date range) will not have the same performance. For more than millions of records it is recommended to either set a low connection timeout on PostgreSQL or to disable use of the Sort Extension.
+To configure **stac-fastapi-pgstac** to [hydrate search result items in the API](https://stac-utils.github.io/pgstac/pgstac/#runtime-configurations), set the `USE_API_HYDRATE` environment variable to `true` or explicitly set the option in the PGStac Settings object.
 
-`stac-fastapi pgstac` was initially added to `stac-fastapi` by [developmentseed](https://github.com/developmentseed).
+### Migrations
 
-## Installation
+There is a Python utility as part of PgSTAC ([pypgstac](https://stac-utils.github.io/pgstac/pypgstac/)) that includes a migration utility.
+To use:
 
 ```shell
-git clone https://github.com/stac-utils/stac-fastapi.git
-cd stac-fastapi
-pip install -e \
-    stac_fastapi/api[dev] \
-    stac_fastapi/types[dev] \
-    stac_fastapi/extensions[dev] \
-    stac_fastapi/pgstac[dev,server]
+pypgstac migrate
 ```
 
-### Settings
+## Contributing
 
-To configure PGStac stac-fastapi to [hydrate search result items in the API](https://github.com/stac-utils/pgstac#runtime-configurations), set the `USE_API_HYDRATE` environment variable to `true` or explicitly set the option in the PGStac Settings object.
+See [CONTRIBUTING](https://github.com/stac-utils/stac-fastapi-pgstac/blob/main/CONTRIBUTING.md) for detailed contribution instructions.
 
-### Migrations
+To install:
+
+```shell
+git clone https://github.com/stac-utils/stac-fastapi-pgstac
+cd stac-fastapi-pgstac
+pip install -e ".[dev,server,docs]"
+```
+
+To test:
+
+```shell
+make test
+```
 
-PGStac is an external project and the may be used by multiple front ends.
-For Stac FastAPI development, a docker image (which is pulled as part of the docker-compose) is available at
-bitner/pgstac:[version] that has the full database already set up for PGStac.
+Use Github [Pull Requests](https://github.com/stac-utils/stac-fastapi-pgstac/pulls) to provide new features or to request review of draft code, and use [Issues](https://github.com/stac-utils/stac-fastapi-pgstac/issues) to report bugs or request new features.
 
-There is also a python utility as part of PGStac (pypgstac) that includes a migration utility. The pgstac
-version required by stac-fastapi/pgstac is pinned by using the pinned version of pypgstac in the [setup](http://github.com/stac-utils/stac-fastapi-pgstac/blob/main/setup.py) file.
+### Documentation
 
-In order to migrate database versions you can use the migration utility:
+To build the docs:
 
 ```shell
-pypgstac migrate
+make docs
+```
+
+Then, serve the docs via a local HTTP server:
+
+```shell
+mkdocs serve
 ```
+
+## History
+
+**stac-fastapi-pgstac** was initially added to **stac-fastapi** by [developmentseed](https://github.com/developmentseed).
+In April of 2023, it was removed from the core **stac-fastapi** repository and moved to its current location (<http://github.com/stac-util/stac-fastapi-pgstac>).
+
+## License
+
+[MIT](https://github.com/stac-utils/stac-fastapi-pgstac/blob/main/LICENSE)
+
+<!-- markdownlint-disable-file MD033 -->