diff --git a/.github/workflows/deploy_mkdocs.yml b/.github/workflows/deploy_mkdocs.yml new file mode 100644 index 000000000..833c1021f --- /dev/null +++ b/.github/workflows/deploy_mkdocs.yml @@ -0,0 +1,48 @@ +name: Publish docs via GitHub Pages + +on: + push: + 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_PORT: 8082 + ES_PORT: 9202 + + - name: Deploy docs + run: mkdocs gh-deploy --force -f docs/mkdocs.yml \ No newline at end of file diff --git a/.gitignore b/.gitignore index 81ab98af0..e66d06727 100644 --- a/.gitignore +++ b/.gitignore @@ -135,4 +135,6 @@ dmypy.json # Virtualenv venv +/docs/src/api/* + .DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md index ab946d894..5bdeee6db 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..7f25e87ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +Issues and pull requests are more than welcome. + + +### 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 install +pre-commit run --all-files +``` + +### Testing + +```shell +make test +``` +Test against OpenSearch only + +```shell +make test-opensearch +``` + +Test against Elasticsearch only + +```shell +make test-elasticsearch +``` + +### Docs + +```shell +make docs +``` + +Hot-reloading docs locally: + +```shell +mkdocs serve -f docs/mkdocs.yml +``` diff --git a/Makefile b/Makefile index 3025a3e47..26ed0361f 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/README.md b/README.md index 0b7a49bbf..37cf3a4f3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,33 @@ # 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) + +--- + +**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: - 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: @@ -18,35 +38,7 @@ or ``` 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 -``` - + ## Build Elasticsearh API backend ```shell @@ -120,22 +112,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/docker-compose.docs.yml b/docker-compose.docs.yml new file mode 100644 index 000000000..4d91a06b4 --- /dev/null +++ b/docker-compose.docs.yml @@ -0,0 +1,14 @@ +version: '3' + +services: + docs: + container_name: stac-fastapi-docs-dev + build: + context: . + dockerfile: dockerfiles/Dockerfile.docs + platform: linux/amd64 + environment: + - APP_PORT=8082 + - ES_PORT=9202 + volumes: + - .:/opt/src \ No newline at end of file diff --git a/dockerfiles/Dockerfile.docs b/dockerfiles/Dockerfile.docs new file mode 100644 index 000000000..f1fe63b8d --- /dev/null +++ b/dockerfiles/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/core \ + stac_fastapi/elasticsearch \ + stac_fastapi/opensearch + +CMD ["pdocs", \ + "as_markdown", \ + "--output_dir", \ + "docs/src/api/", \ + "--exclude_source", \ + "--overwrite", \ + "stac_fastapi"] \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 000000000..5968ffa61 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,103 @@ +site_name: stac-fastapi-elasticsearch-opensearch +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/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 + - API: + - stac_fastapi.elasticsearch: + - app: api/stac_fastapi/elasticsearch/app.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 + - 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: + - 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 + - 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 + - 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" + +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/contributing.md b/docs/src/contributing.md new file mode 120000 index 000000000..f939e75f2 --- /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 120000 index 000000000..fe8400541 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1 @@ +../../README.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 000000000..699cc9e7b --- /dev/null +++ b/docs/src/release-notes.md @@ -0,0 +1 @@ +../../CHANGELOG.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 000000000..353eb887c --- /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 diff --git a/docs/src/tips-and-tricks.md b/docs/src/tips-and-tricks.md new file mode 100644 index 000000000..27919e5ca --- /dev/null +++ b/docs/src/tips-and-tricks.md @@ -0,0 +1,3 @@ +# Tips and Tricks + +This page contains a few 'tips and tricks' for working with **sfeos**.