first pass

Author: jonhealy1

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

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

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

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

docs/src/release-notes.md

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

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.