Merge pull request #223 from stac-utils/makedocs

Make docs

.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

.gitignore

@@ -135,4 +135,6 @@ dmypy.json
 # Virtualenv
 venv
 
+/docs/src/api/*
+
 .DS_Store

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

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
+```

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

README.md

@@ -1,13 +1,33 @@
 # stac-fastapi-elasticsearch-opensearch (sfeos)
 
-## Elasticsearch and Opensearch backends for the stac-fastapi project  
+<!-- markdownlint-disable MD033 MD041 -->
+
+<p align="left">
+  <img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=600>
+  <p align="left"><b>Elasticsearch and Opensearch backends for the stac-fastapi project.</b></p>
+
 
   [![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
 

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

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"]

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

docs/src/contributing.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

docs/src/index.md

@@ -0,0 +1 @@
+../../README.md

docs/src/release-notes.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/src/stylesheets/extra.css

@@ -0,0 +1,3 @@
+:root {
+    --md-primary-fg-color:        rgb(13, 118, 160);
+  }

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**.