From b360423dc760a0a59fd263182ff420c473652c84 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Tue, 9 Apr 2024 22:55:57 +0800 Subject: [PATCH 01/12] first pass --- Dockerfile.docs | 24 ++++++++++++ Makefile | 10 +++++ docker-compose.docs.yml | 18 +++++++++ docs/mkdocs.yml | 78 +++++++++++++++++++++++++++++++++++++ docs/src/release-notes.md | 1 + docs/src/tips-and-tricks.md | 33 ++++++++++++++++ 6 files changed, 164 insertions(+) create mode 100644 Dockerfile.docs create mode 100644 docker-compose.docs.yml create mode 100644 docs/mkdocs.yml create mode 100644 docs/src/release-notes.md create mode 100644 docs/src/tips-and-tricks.md diff --git a/Dockerfile.docs b/Dockerfile.docs new file mode 100644 index 00000000..ee21d100 --- /dev/null +++ b/Dockerfile.docs @@ -0,0 +1,24 @@ +FROM python:3.8-slim + +# build-essential is required to build a wheel for ciso8601 +RUN apt update && apt install -y build-essential + +RUN python -m pip install --upgrade pip +RUN python -m pip install mkdocs mkdocs-material pdocs + +COPY . /opt/src + +WORKDIR /opt/src + +RUN python -m pip install \ + stac_fastapi/api \ + stac_fastapi/types \ + stac_fastapi/elasticsearch + +CMD ["pdocs", \ + "as_markdown", \ + "--output_dir", \ + "docs/elasticsearch/", \ + "--exclude_source", \ + "--overwrite", \ + "stac_fastapi.elasticsearch"] \ No newline at end of file diff --git a/Makefile b/Makefile index 3025a3e4..26ed0361 100644 --- a/Makefile +++ b/Makefile @@ -104,3 +104,13 @@ install-es: pybase-install .PHONY: install-os install-os: pybase-install pip install -e ./stac_fastapi/opensearch[dev,server] + +.PHONY: docs-image +docs-image: + docker-compose -f docker-compose.docs.yml \ + build + +.PHONY: docs +docs: docs-image + docker-compose -f docker-compose.docs.yml \ + run docs \ No newline at end of file diff --git a/docker-compose.docs.yml b/docker-compose.docs.yml new file mode 100644 index 00000000..38ebf41b --- /dev/null +++ b/docker-compose.docs.yml @@ -0,0 +1,18 @@ +version: '3' + +services: + docs: + container_name: stac-fastapi-docs-dev + build: + context: . + dockerfile: Dockerfile.docs + platform: linux/amd64 + environment: + - POSTGRES_USER=username + - POSTGRES_PASS=password + - POSTGRES_DBNAME=postgis + - POSTGRES_HOST_READER=database + - POSTGRES_HOST_WRITER=database + - POSTGRES_PORT=5432 + volumes: + - .:/opt/src \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 00000000..1f0471b7 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,78 @@ +site_name: stac-fastapi-elasticsearch-opensearch +site_description: STAC FastAPI. + +# Repository +repo_name: "stac-utils/stac-fastapi-elasticsearch-opensearch" +repo_url: "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch" +edit_uri: "blob/main/docs/src/" + +docs_dir: 'src' +site_dir: 'build' + +# Social links +extra: + social: + - icon: "fontawesome/brands/github" + link: "https://github.com/stac-utils" + +# Layout +nav: + - Home: "index.md" + - Tips and Tricks: tips-and-tricks.md + - ELASTICSEARCH: + - packages: elasticsearch/stac_fastapi/index.md + - stac_fastapi.elasticsearch: + - module: elasticsearch/stac_fastapi/elasticsearch/index.md + - app: elasticsearch/stac_fastapi/elasticsearch/app.md + - config: elasticsearch/stac_fastapi/elasticsearch/config.md + - database_logic: elasticsearch/stac_fastapi/elasticsearch/database_logic.md + - version: elasticsearch/stac_fastapi/elasticsearch/version.md + - Development - Contributing: "contributing.md" + - Release Notes: "release-notes.md" + +plugins: + - search + +# Theme +theme: + icon: + logo: "material/home" + repo: "fontawesome/brands/github" + name: "material" + language: "en" + font: + text: "Nunito Sans" + code: "Fira Code" + +extra_css: + - stylesheets/extra.css + +# These extensions are chosen to be a superset of Pandoc's Markdown. +# This way, I can write in Pandoc's Markdown and have it be supported here. +# https://pandoc.org/MANUAL.html +markdown_extensions: + - admonition + - attr_list + - codehilite: + guess_lang: false + - def_list + - footnotes + - pymdownx.arithmatex + - pymdownx.betterem + - pymdownx.caret: + insert: false + - pymdownx.details + - pymdownx.emoji + - pymdownx.escapeall: + hardbreak: true + nbsp: true + - pymdownx.magiclink: + hide_protocol: true + repo_url_shortener: true + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde + - toc: + permalink: true \ No newline at end of file diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md new file mode 100644 index 00000000..699cc9e7 --- /dev/null +++ b/docs/src/release-notes.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file diff --git a/docs/src/tips-and-tricks.md b/docs/src/tips-and-tricks.md new file mode 100644 index 00000000..587afe52 --- /dev/null +++ b/docs/src/tips-and-tricks.md @@ -0,0 +1,33 @@ +# Tips and Tricks + +This page contains a few 'tips and tricks' for getting **stac-fastapi** working in various situations. + +## Get stac-fastapi working with CORS + +CORS (Cross-Origin Resource Sharing) support may be required to use stac-fastapi in certain situations. +For example, if you are running [stac-browser](https://github.com/radiantearth/stac-browser) to browse the STAC catalog created by **stac-fastapi**, then you will need to enable CORS support. +To do this, edit your backend's `app.py` and add the following import: + +```python +from fastapi.middleware.cors import CORSMiddleware +``` + +and then edit the `api = StacApi(...` call to add the following parameter: + +```python +middlewares=[lambda app: CORSMiddleware(app, allow_origins=["*"])] +``` + +If needed, you can edit the `allow_origins` parameter to only allow CORS requests from specific origins. + +## Enable the Context extension + +The Context STAC extension provides information on the number of items matched and returned from a STAC search. +This is required by various other STAC-related tools, such as the pystac command-line client. +To enable the extension, edit your backend's `app.py` and add the following import: + +```python +from stac_fastapi.extensions.core.context import ContextExtension +``` + +and then edit the `api = StacApi(...` call to add `ContextExtension()` to the list given as the `extensions` parameter. \ No newline at end of file From 60c64791056c4d380f70939f8c751e67ac096af6 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 00:23:31 +0800 Subject: [PATCH 02/12] second pass --- .gitignore | 2 ++ CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++ Dockerfile.docs | 18 +++++++++---- docker-compose.docs.yml | 19 +++++++++----- docs/mkdocs.yml | 40 +++++++++++++++++++++------- docs/src/contributing.md | 1 + docs/src/index.md | 1 + docs/src/stylesheets/extra.css | 3 +++ 8 files changed, 112 insertions(+), 20 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/src/contributing.md create mode 100644 docs/src/index.md create mode 100644 docs/src/stylesheets/extra.css diff --git a/.gitignore b/.gitignore index 81ab98af..276e1db2 100644 --- a/.gitignore +++ b/.gitignore @@ -135,4 +135,6 @@ dmypy.json # Virtualenv venv +/docs/src/api + .DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..012e3b5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing + +Issues and pull requests are more than welcome. + +**dev install** + +```bash +git clone https://github.com/stac-utils/stac-fastapi.git +cd stac-fastapi +python -m pip install -e stac_fastapi/api[dev] +``` + +**pre-commit** + +This repo is set to use `pre-commit` to run *ruff*, *pydocstring* and mypy when committing new code. + +```bash +pre-commit install +``` + +### Docs + +```bash +git clone https://github.com/stac-utils/stac-fastapi.git +cd stac-fastapi +python pip install -e stac_fastapi/api["docs"] +``` + +Hot-reloading docs: + +```bash +$ mkdocs serve -f docs/mkdocs.yml +``` + +To manually deploy docs (note you should never need to do this because GitHub +Actions deploys automatically for new commits.): + +```bash +Create API documentations +$ pdocs as_markdown \ + --output_dir docs/src/api/ \ + --exclude_source \ + --overwrite \ + stac_fastapi.opensearch + +# deploy +$ mkdocs gh-deploy -f docs/mkdocs.yml +``` \ No newline at end of file diff --git a/Dockerfile.docs b/Dockerfile.docs index ee21d100..0a159a4c 100644 --- a/Dockerfile.docs +++ b/Dockerfile.docs @@ -11,14 +11,22 @@ COPY . /opt/src WORKDIR /opt/src RUN python -m pip install \ - stac_fastapi/api \ - stac_fastapi/types \ - stac_fastapi/elasticsearch + stac_fastapi/core \ + stac_fastapi/elasticsearch \ + stac_fastapi/opensearch + +# CMD ["pdocs", \ +# "as_markdown", \ +# "--output_dir", \ +# "docs/src/api/", \ +# "--exclude_source", \ +# "--overwrite", \ +# "stac_fastapi.core"] CMD ["pdocs", \ "as_markdown", \ "--output_dir", \ - "docs/elasticsearch/", \ + "docs/src/api/", \ "--exclude_source", \ "--overwrite", \ - "stac_fastapi.elasticsearch"] \ No newline at end of file + "stac_fastapi"] \ No newline at end of file diff --git a/docker-compose.docs.yml b/docker-compose.docs.yml index 38ebf41b..4613da6b 100644 --- a/docker-compose.docs.yml +++ b/docker-compose.docs.yml @@ -8,11 +8,18 @@ services: dockerfile: Dockerfile.docs platform: linux/amd64 environment: - - POSTGRES_USER=username - - POSTGRES_PASS=password - - POSTGRES_DBNAME=postgis - - POSTGRES_HOST_READER=database - - POSTGRES_HOST_WRITER=database - - POSTGRES_PORT=5432 + - STAC_FASTAPI_TITLE=stac-fastapi-opensearch + - STAC_FASTAPI_DESCRIPTION=A STAC FastAPI with an Opensearch backend + - STAC_FASTAPI_VERSION=2.1 + - APP_HOST=0.0.0.0 + - APP_PORT=8082 + - RELOAD=true + - ENVIRONMENT=local + - WEB_CONCURRENCY=10 + - ES_HOST=opensearch + - ES_PORT=9202 + - ES_USE_SSL=false + - ES_VERIFY_CERTS=false + - BACKEND=opensearch volumes: - .:/opt/src \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1f0471b7..7b9d59c2 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -4,7 +4,7 @@ site_description: STAC FastAPI. # Repository repo_name: "stac-utils/stac-fastapi-elasticsearch-opensearch" repo_url: "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch" -edit_uri: "blob/main/docs/src/" +edit_uri: "blob/makedocs/docs/src/" docs_dir: 'src' site_dir: 'build' @@ -17,16 +17,38 @@ extra: # Layout nav: - - Home: "index.md" + - Home: index.md - Tips and Tricks: tips-and-tricks.md - - ELASTICSEARCH: - - packages: elasticsearch/stac_fastapi/index.md + - API: - stac_fastapi.elasticsearch: - - module: elasticsearch/stac_fastapi/elasticsearch/index.md - - app: elasticsearch/stac_fastapi/elasticsearch/app.md - - config: elasticsearch/stac_fastapi/elasticsearch/config.md - - database_logic: elasticsearch/stac_fastapi/elasticsearch/database_logic.md - - version: elasticsearch/stac_fastapi/elasticsearch/version.md + - app: api/stac_fastapi/elasticsearch/app.md + - module: api/stac_fastapi/elasticsearch/index.md + - config: api/stac_fastapi/elasticsearch/config.md + - database_logic: api/stac_fastapi/elasticsearch/database_logic.md + - index: api/stac_fastapi/elasticsearch/index.md + - version: api/stac_fastapi/elasticsearch/version.md + - stac_fastapi.opensearch: + - app: api/stac_fastapi/opensearch/app.md + - module: api/stac_fastapi/opensearch/index.md + - config: api/stac_fastapi/opensearch/config.md + - database_logic: api/stac_fastapi/opensearch/database_logic.md + - index: api/stac_fastapi/opensearch/index.md + - version: api/stac_fastapi/opensearch/version.md + - stac_fastapi.core: + - module: api/stac_fastapi/core/index.md + - base_database_logic: api/stac_fastapi/core/base_database_logic.md + - base_settings: api/stac_fastapi/core/base_settings.md + - core: api/stac_fastapi/core/core.md + - extensions: + - module: api/stac_fastapi/core/extensions/index.md + - filter: api/stac_fastapi/core/extensions/filter.md + - query: api/stac_fastapi/core/extensions/query.md + - models: + - module: api/stac_fastapi/core/models/index.md + - links: api/stac_fastapi/core/models/links.md + - search: api/stac_fastapi/core/models/search.md + - serializers: api/stac_fastapi/core/serializers.md + - version: api/stac_fastapi/core/version.md - Development - Contributing: "contributing.md" - Release Notes: "release-notes.md" diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 100644 index 00000000..f939e75f --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..fe840054 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/docs/src/stylesheets/extra.css b/docs/src/stylesheets/extra.css new file mode 100644 index 00000000..353eb887 --- /dev/null +++ b/docs/src/stylesheets/extra.css @@ -0,0 +1,3 @@ +:root { + --md-primary-fg-color: rgb(13, 118, 160); + } \ No newline at end of file From 55545300b9897ebaefb3aeb1fed2ef14a08c7f55 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 01:29:21 +0800 Subject: [PATCH 03/12] clean up dockerfile --- Dockerfile.docs | 8 -------- 1 file changed, 8 deletions(-) diff --git a/Dockerfile.docs b/Dockerfile.docs index 0a159a4c..f1fe63b8 100644 --- a/Dockerfile.docs +++ b/Dockerfile.docs @@ -15,14 +15,6 @@ RUN python -m pip install \ stac_fastapi/elasticsearch \ stac_fastapi/opensearch -# CMD ["pdocs", \ -# "as_markdown", \ -# "--output_dir", \ -# "docs/src/api/", \ -# "--exclude_source", \ -# "--overwrite", \ -# "stac_fastapi.core"] - CMD ["pdocs", \ "as_markdown", \ "--output_dir", \ From e3bd85f3d0bceaf83d884911fcc01ff914d1d11d Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 01:29:33 +0800 Subject: [PATCH 04/12] add gh workflow --- .github/workflows/deploy_mkdocs.yml | 53 +++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/deploy_mkdocs.yml diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml new file mode 100644 index 00000000..eb297b08 --- /dev/null +++ b/.github/workflows/deploy_mkdocs.yml @@ -0,0 +1,53 @@ +name: Publish docs via GitHub Pages + +on: + pull_request: + branches: + - main + paths: + # Rebuild website when docs have changed or code has changed + - "README.md" + - "docs/**" + - "**.py" + workflow_dispatch: + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + + steps: + - name: Checkout main + uses: actions/checkout@v4 + + - name: Set up Python 3.8 + uses: actions/setup-python@v5 + with: + python-version: 3.8 + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install \ + stac_fastapi/core \ + stac_fastapi/elasticsearch[docs] \ + stac_fastapi/opensearch \ + + - name: update API docs + run: | + pdocs as_markdown \ + --output_dir docs/src/api/ \ + --exclude_source \ + --overwrite \ + stac_fastapi + env: + APP_HOST: 0.0.0.0 + APP_PORT: 8082 + ES_HOST: opensearch + ES_PORT: 9202 + ES_USE_SSL: false + ES_VERIFY_CERTS: false + BACKEND: opensearch + + - name: Deploy docs + run: mkdocs gh-deploy --force -f docs/mkdocs.yml \ No newline at end of file From 1380655c5593098bed9e4c1236831aedb32c0922 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 01:59:59 +0800 Subject: [PATCH 05/12] mkdocs update --- docs/mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7b9d59c2..a112ac56 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,5 @@ site_name: stac-fastapi-elasticsearch-opensearch -site_description: STAC FastAPI. +site_description: STAC FastAPI Elasticsearch and Opensearch backends. # Repository repo_name: "stac-utils/stac-fastapi-elasticsearch-opensearch" @@ -17,7 +17,7 @@ extra: # Layout nav: - - Home: index.md + - Home: "index.md" - Tips and Tricks: tips-and-tricks.md - API: - stac_fastapi.elasticsearch: From 9ad486d36031e3cfd7b2c0d372cfb6a0db845400 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 11:07:30 +0800 Subject: [PATCH 06/12] update gitignore --- .gitignore | 2 +- docs/src/index.md | 0 2 files changed, 1 insertion(+), 1 deletion(-) mode change 100644 => 120000 docs/src/index.md diff --git a/.gitignore b/.gitignore index 276e1db2..e66d0672 100644 --- a/.gitignore +++ b/.gitignore @@ -135,6 +135,6 @@ dmypy.json # Virtualenv venv -/docs/src/api +/docs/src/api/* .DS_Store diff --git a/docs/src/index.md b/docs/src/index.md deleted file mode 100644 index fe840054..00000000 --- a/docs/src/index.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md new file mode 120000 index 00000000..fe840054 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file From 64ebe71bc8effc2fc000f26f4dcf71b1af218e80 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 11:34:07 +0800 Subject: [PATCH 07/12] add logo to readme --- README.md | 17 ++++++++++++++++- docs/src/contributing.md | 0 docs/src/release-notes.md | 0 3 files changed, 16 insertions(+), 1 deletion(-) mode change 100644 => 120000 docs/src/contributing.md mode change 100644 => 120000 docs/src/release-notes.md diff --git a/README.md b/README.md index 0b7a49bb..d88ae058 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,23 @@ # stac-fastapi-elasticsearch-opensearch (sfeos) -## Elasticsearch and Opensearch backends for the stac-fastapi project + + +

+ +

Elasticsearch and Opensearch backends for the stac-fastapi project.

+ [![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch) + +--- + +**Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/) + +**Source Code**: [https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch) + +--- + +### Notes: - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example. - Reach out on our [Gitter](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) channel or feel free to add to our [Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) page here on github. diff --git a/docs/src/contributing.md b/docs/src/contributing.md deleted file mode 100644 index f939e75f..00000000 --- a/docs/src/contributing.md +++ /dev/null @@ -1 +0,0 @@ -../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/contributing.md b/docs/src/contributing.md new file mode 120000 index 00000000..f939e75f --- /dev/null +++ b/docs/src/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md deleted file mode 100644 index 699cc9e7..00000000 --- a/docs/src/release-notes.md +++ /dev/null @@ -1 +0,0 @@ -../../CHANGELOG.md \ No newline at end of file diff --git a/docs/src/release-notes.md b/docs/src/release-notes.md new file mode 120000 index 00000000..699cc9e7 --- /dev/null +++ b/docs/src/release-notes.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file From b795502d4dfe912def9545dc12f82d631b9bb128 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 12:22:33 +0800 Subject: [PATCH 08/12] update --- .github/workflows/deploy_mkdocs.yml | 7 +------ docs/mkdocs.yml | 11 +++++++---- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml index eb297b08..833c1021 100644 --- a/.github/workflows/deploy_mkdocs.yml +++ b/.github/workflows/deploy_mkdocs.yml @@ -1,7 +1,7 @@ name: Publish docs via GitHub Pages on: - pull_request: + push: branches: - main paths: @@ -41,13 +41,8 @@ jobs: --overwrite \ stac_fastapi env: - APP_HOST: 0.0.0.0 APP_PORT: 8082 - ES_HOST: opensearch ES_PORT: 9202 - ES_USE_SSL: false - ES_VERIFY_CERTS: false - BACKEND: opensearch - name: Deploy docs run: mkdocs gh-deploy --force -f docs/mkdocs.yml \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a112ac56..5968ffa6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -4,7 +4,7 @@ site_description: STAC FastAPI Elasticsearch and Opensearch backends. # Repository repo_name: "stac-utils/stac-fastapi-elasticsearch-opensearch" repo_url: "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch" -edit_uri: "blob/makedocs/docs/src/" +edit_uri: "blob/main/docs/src/" docs_dir: 'src' site_dir: 'build' @@ -22,23 +22,24 @@ nav: - API: - stac_fastapi.elasticsearch: - app: api/stac_fastapi/elasticsearch/app.md - - module: api/stac_fastapi/elasticsearch/index.md + - index: api/stac_fastapi/elasticsearch/index.md - config: api/stac_fastapi/elasticsearch/config.md - database_logic: api/stac_fastapi/elasticsearch/database_logic.md - index: api/stac_fastapi/elasticsearch/index.md - version: api/stac_fastapi/elasticsearch/version.md - stac_fastapi.opensearch: - app: api/stac_fastapi/opensearch/app.md - - module: api/stac_fastapi/opensearch/index.md + - index: api/stac_fastapi/opensearch/index.md - config: api/stac_fastapi/opensearch/config.md - database_logic: api/stac_fastapi/opensearch/database_logic.md - index: api/stac_fastapi/opensearch/index.md - version: api/stac_fastapi/opensearch/version.md - stac_fastapi.core: - - module: api/stac_fastapi/core/index.md + - index: api/stac_fastapi/core/index.md - base_database_logic: api/stac_fastapi/core/base_database_logic.md - base_settings: api/stac_fastapi/core/base_settings.md - core: api/stac_fastapi/core/core.md + - datetime_utils: api/stac_fastapi/core/datetime_utils.md - extensions: - module: api/stac_fastapi/core/extensions/index.md - filter: api/stac_fastapi/core/extensions/filter.md @@ -48,6 +49,8 @@ nav: - links: api/stac_fastapi/core/models/links.md - search: api/stac_fastapi/core/models/search.md - serializers: api/stac_fastapi/core/serializers.md + - session: api/stac_fastapi/core/session.md + - utilities: api/stac_fastapi/core/utilities.md - version: api/stac_fastapi/core/version.md - Development - Contributing: "contributing.md" - Release Notes: "release-notes.md" From 5b3c4352fa04314194ffbbbd7e88625ab663b36c Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 12:22:52 +0800 Subject: [PATCH 09/12] update documentation --- CONTRIBUTING.md | 70 +++++++++++++++++++++---------------- README.md | 44 ++--------------------- docs/src/tips-and-tricks.md | 32 +---------------- 3 files changed, 43 insertions(+), 103 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 012e3b5e..7f25e87a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,48 +1,58 @@ # Contributing Issues and pull requests are more than welcome. + -**dev install** +### Development Environment Setup -```bash -git clone https://github.com/stac-utils/stac-fastapi.git -cd stac-fastapi -python -m pip install -e stac_fastapi/api[dev] +To install the classes in your local Python env, run: + +```shell +pip install -e 'stac_fastapi/elasticsearch[dev]' +``` + +or + +```shell +pip install -e 'stac_fastapi/opensearch[dev]' ``` -**pre-commit** +### Pre-commit -This repo is set to use `pre-commit` to run *ruff*, *pydocstring* and mypy when committing new code. +Install [pre-commit](https://pre-commit.com/#install). -```bash +Prior to commit, run: + +```shell pre-commit install -``` +pre-commit run --all-files +``` -### Docs +### Testing -```bash -git clone https://github.com/stac-utils/stac-fastapi.git -cd stac-fastapi -python pip install -e stac_fastapi/api["docs"] +```shell +make test ``` +Test against OpenSearch only -Hot-reloading docs: - -```bash -$ mkdocs serve -f docs/mkdocs.yml +```shell +make test-opensearch ``` -To manually deploy docs (note you should never need to do this because GitHub -Actions deploys automatically for new commits.): +Test against Elasticsearch only + +```shell +make test-elasticsearch +``` -```bash -Create API documentations -$ pdocs as_markdown \ - --output_dir docs/src/api/ \ - --exclude_source \ - --overwrite \ - stac_fastapi.opensearch +### Docs -# deploy -$ mkdocs gh-deploy -f docs/mkdocs.yml -``` \ No newline at end of file +```shell +make docs +``` + +Hot-reloading docs locally: + +```shell +mkdocs serve -f docs/mkdocs.yml +``` diff --git a/README.md b/README.md index d88ae058..878ae587 100644 --- a/README.md +++ b/README.md @@ -36,32 +36,8 @@ pip install stac_fastapi.opensearch #### For changes, see the [Changelog](CHANGELOG.md) - -## Development Environment Setup - -To install the classes in your local Python env, run: - -```shell -pip install -e 'stac_fastapi/elasticsearch[dev]' -``` - -or - -```shell -pip install -e 'stac_fastapi/opensearch[dev]' -``` - - -### Pre-commit - -Install [pre-commit](https://pre-commit.com/#install). - -Prior to commit, run: - -```shell -pre-commit run --all-files -``` - +#### Development notes: [Contributing](CONTRIBUTING.md) + ## Build Elasticsearh API backend ```shell @@ -135,22 +111,6 @@ Options: python3 data_loader.py --base-url http://localhost:8080 ``` -## Testing - -```shell -make test -``` -Test against OpenSearch only - -```shell -make test-opensearch -``` - -Test against Elasticsearch only - -```shell -make test-elasticsearch -``` ## Elasticsearch Mappings diff --git a/docs/src/tips-and-tricks.md b/docs/src/tips-and-tricks.md index 587afe52..27919e5c 100644 --- a/docs/src/tips-and-tricks.md +++ b/docs/src/tips-and-tricks.md @@ -1,33 +1,3 @@ # Tips and Tricks -This page contains a few 'tips and tricks' for getting **stac-fastapi** working in various situations. - -## Get stac-fastapi working with CORS - -CORS (Cross-Origin Resource Sharing) support may be required to use stac-fastapi in certain situations. -For example, if you are running [stac-browser](https://github.com/radiantearth/stac-browser) to browse the STAC catalog created by **stac-fastapi**, then you will need to enable CORS support. -To do this, edit your backend's `app.py` and add the following import: - -```python -from fastapi.middleware.cors import CORSMiddleware -``` - -and then edit the `api = StacApi(...` call to add the following parameter: - -```python -middlewares=[lambda app: CORSMiddleware(app, allow_origins=["*"])] -``` - -If needed, you can edit the `allow_origins` parameter to only allow CORS requests from specific origins. - -## Enable the Context extension - -The Context STAC extension provides information on the number of items matched and returned from a STAC search. -This is required by various other STAC-related tools, such as the pystac command-line client. -To enable the extension, edit your backend's `app.py` and add the following import: - -```python -from stac_fastapi.extensions.core.context import ContextExtension -``` - -and then edit the `api = StacApi(...` call to add `ContextExtension()` to the list given as the `extensions` parameter. \ No newline at end of file +This page contains a few 'tips and tricks' for working with **sfeos**. From cd0cfb605c6b40c0f961d3a595b972d06b644b19 Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 12:29:04 +0800 Subject: [PATCH 10/12] add contributions note to readme --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 878ae587..37cf3a4f 100644 --- a/README.md +++ b/README.md @@ -11,10 +11,11 @@ --- -**Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/) +**Online Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/) **Source Code**: [https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch) + --- ### Notes: @@ -22,7 +23,11 @@ - Our Api core library can be used to create custom backends. See [stac-fastapi-mongo](https://github.com/Healy-Hyperspatial/stac-fastapi-mongo) for a working example. - Reach out on our [Gitter](https://app.gitter.im/#/room/#stac-fastapi-elasticsearch_community:gitter.im) channel or feel free to add to our [Discussions](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions) page here on github. - There is [Postman](https://documenter.getpostman.com/view/12888943/2s8ZDSdRHA) documentation here for examples on how to run some of the API routes locally - after starting the elasticsearch backend via the docker-compose.yml file. -- The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes. +- The `/examples` folder shows an example of running stac-fastapi-elasticsearch from PyPI in docker without needing any code from the repository. There is also a Postman collection here that you can load into Postman for testing the API routes. + +- For changes, see the [Changelog](CHANGELOG.md) +- We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md) + ### To install from PyPI: @@ -33,10 +38,6 @@ or ``` pip install stac_fastapi.opensearch ``` - -#### For changes, see the [Changelog](CHANGELOG.md) - -#### Development notes: [Contributing](CONTRIBUTING.md) ## Build Elasticsearh API backend From e7a029d5521d4117751aa1cd4e6a8a37b9acb89e Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 12:37:20 +0800 Subject: [PATCH 11/12] update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ab946d89..5bdeee6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - use index templates for Collection and Item indices [#208](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions/208) - Added API `title`, `version`, and `description` parameters from environment variables `STAC_FASTAPI_TITLE`, `STAC_FASTAPI_VERSION` and `STAC_FASTAPI_DESCRIPTION`, respectively. [#207](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/207) - Added a `STAC_FASTAPI_ROOT_PATH` environment variable to define the root path. Useful when working with an API gateway or load balancer. [#221](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/221) +- Added mkdocs, pdocs, to generate docs and push to gh pages via workflow. Updated documentation. [#223](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/pull/223) ### Changed From f841731239cdcf5467d363f9e55cc0bba5d4d1db Mon Sep 17 00:00:00 2001 From: jonhealy1 Date: Wed, 10 Apr 2024 12:53:28 +0800 Subject: [PATCH 12/12] move dockerfiles --- docker-compose.docs.yml | 13 +------------ Dockerfile.docs => dockerfiles/Dockerfile.docs | 0 2 files changed, 1 insertion(+), 12 deletions(-) rename Dockerfile.docs => dockerfiles/Dockerfile.docs (100%) diff --git a/docker-compose.docs.yml b/docker-compose.docs.yml index 4613da6b..4d91a06b 100644 --- a/docker-compose.docs.yml +++ b/docker-compose.docs.yml @@ -5,21 +5,10 @@ services: container_name: stac-fastapi-docs-dev build: context: . - dockerfile: Dockerfile.docs + dockerfile: dockerfiles/Dockerfile.docs platform: linux/amd64 environment: - - STAC_FASTAPI_TITLE=stac-fastapi-opensearch - - STAC_FASTAPI_DESCRIPTION=A STAC FastAPI with an Opensearch backend - - STAC_FASTAPI_VERSION=2.1 - - APP_HOST=0.0.0.0 - APP_PORT=8082 - - RELOAD=true - - ENVIRONMENT=local - - WEB_CONCURRENCY=10 - - ES_HOST=opensearch - ES_PORT=9202 - - ES_USE_SSL=false - - ES_VERIFY_CERTS=false - - BACKEND=opensearch volumes: - .:/opt/src \ No newline at end of file diff --git a/Dockerfile.docs b/dockerfiles/Dockerfile.docs similarity index 100% rename from Dockerfile.docs rename to dockerfiles/Dockerfile.docs