Skip to content

Commit 8d017dd

Browse files
jonhealy1jonhealy1
authored
Merge pull request #223 from stac-utils/makedocs
Make docs
2 parents be114d9 + f841731 commit 8d017dd

File tree

14 files changed

+292
-47
lines changed

14 files changed

+292
-47
lines changed

‎.github/workflows/deploy_mkdocs.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Publish docs via GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
# Rebuild website when docs have changed or code has changed
9+
- "README.md"
10+
- "docs/**"
11+
- "**.py"
12+
workflow_dispatch:
13+
14+
jobs:
15+
build:
16+
name: Deploy docs
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout main
21+
uses: actions/checkout@v4
22+
23+
- name: Set up Python 3.8
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: 3.8
27+
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
python -m pip install \
32+
stac_fastapi/core \
33+
stac_fastapi/elasticsearch[docs] \
34+
stac_fastapi/opensearch \
35+
36+
- name: update API docs
37+
run: |
38+
pdocs as_markdown \
39+
--output_dir docs/src/api/ \
40+
--exclude_source \
41+
--overwrite \
42+
stac_fastapi
43+
env:
44+
APP_PORT: 8082
45+
ES_PORT: 9202
46+
47+
- name: Deploy docs
48+
run: mkdocs gh-deploy --force -f docs/mkdocs.yml

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,4 +135,6 @@ dmypy.json
135135
# Virtualenv
136136
venv
137137

138+
/docs/src/api/*
139+
138140
.DS_Store

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
1212
- use index templates for Collection and Item indices [#208](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch/discussions/208)
1313
- 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)
1414
- 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)
15+
- 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)
1516

1617

1718
### Changed

‎CONTRIBUTING.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Contributing
2+
3+
Issues and pull requests are more than welcome.
4+
5+
6+
### Development Environment Setup
7+
8+
To install the classes in your local Python env, run:
9+
10+
```shell
11+
pip install -e 'stac_fastapi/elasticsearch[dev]'
12+
```
13+
14+
or
15+
16+
```shell
17+
pip install -e 'stac_fastapi/opensearch[dev]'
18+
```
19+
20+
### Pre-commit
21+
22+
Install [pre-commit](https://pre-commit.com/#install).
23+
24+
Prior to commit, run:
25+
26+
```shell
27+
pre-commit install
28+
pre-commit run --all-files
29+
```
30+
31+
### Testing
32+
33+
```shell
34+
make test
35+
```
36+
Test against OpenSearch only
37+
38+
```shell
39+
make test-opensearch
40+
```
41+
42+
Test against Elasticsearch only
43+
44+
```shell
45+
make test-elasticsearch
46+
```
47+
48+
### Docs
49+
50+
```shell
51+
make docs
52+
```
53+
54+
Hot-reloading docs locally:
55+
56+
```shell
57+
mkdocs serve -f docs/mkdocs.yml
58+
```

‎Makefile‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,3 +104,13 @@ install-es: pybase-install
104104
.PHONY: install-os
105105
install-os: pybase-install
106106
pip install -e ./stac_fastapi/opensearch[dev,server]
107+
108+
.PHONY: docs-image
109+
docs-image:
110+
docker-compose -f docker-compose.docs.yml \
111+
build
112+
113+
.PHONY: docs
114+
docs: docs-image
115+
docker-compose -f docker-compose.docs.yml \
116+
run docs

‎README.md‎

Lines changed: 23 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,33 @@
11
# stac-fastapi-elasticsearch-opensearch (sfeos)
22

3-
## Elasticsearch and Opensearch backends for the stac-fastapi project
3+
<!-- markdownlint-disable MD033 MD041 -->
4+
5+
<p align="left">
6+
<img src="https://github.com/radiantearth/stac-site/raw/master/images/logo/stac-030-long.png" width=600>
7+
<p align="left"><b>Elasticsearch and Opensearch backends for the stac-fastapi project.</b></p>
8+
49

510
[![PyPI version](https://badge.fury.io/py/stac-fastapi.elasticsearch.svg)](https://badge.fury.io/py/stac-fastapi.elasticsearch)
11+
12+
---
13+
14+
**Online Documentation**: [https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch](https://stac-utils.github.io/stac-fastapi-elasticsearch-opensearch/)
15+
16+
**Source Code**: [https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch](https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch)
17+
18+
19+
---
20+
21+
### Notes:
622

723
- 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.
824
- 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.
925
- 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.
10-
- 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.
26+
- 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.
27+
28+
- For changes, see the [Changelog](CHANGELOG.md)
29+
- We are always welcoming contributions. For the development notes: [Contributing](CONTRIBUTING.md)
30+
1131

1232
### To install from PyPI:
1333

@@ -18,35 +38,7 @@ or
1838
```
1939
pip install stac_fastapi.opensearch
2040
```
21-
22-
#### For changes, see the [Changelog](CHANGELOG.md)
23-
24-
25-
## Development Environment Setup
26-
27-
To install the classes in your local Python env, run:
28-
29-
```shell
30-
pip install -e 'stac_fastapi/elasticsearch[dev]'
31-
```
32-
33-
or
34-
35-
```shell
36-
pip install -e 'stac_fastapi/opensearch[dev]'
37-
```
38-
39-
40-
### Pre-commit
41-
42-
Install [pre-commit](https://pre-commit.com/#install).
43-
44-
Prior to commit, run:
45-
46-
```shell
47-
pre-commit run --all-files
48-
```
49-
41+
5042
## Build Elasticsearh API backend
5143

5244
```shell
@@ -120,22 +112,6 @@ Options:
120112
python3 data_loader.py --base-url http://localhost:8080
121113
```
122114

123-
## Testing
124-
125-
```shell
126-
make test
127-
```
128-
Test against OpenSearch only
129-
130-
```shell
131-
make test-opensearch
132-
```
133-
134-
Test against Elasticsearch only
135-
136-
```shell
137-
make test-elasticsearch
138-
```
139115

140116
## Elasticsearch Mappings
141117

‎docker-compose.docs.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: '3'
2+
3+
services:
4+
docs:
5+
container_name: stac-fastapi-docs-dev
6+
build:
7+
context: .
8+
dockerfile: dockerfiles/Dockerfile.docs
9+
platform: linux/amd64
10+
environment:
11+
- APP_PORT=8082
12+
- ES_PORT=9202
13+
volumes:
14+
- .:/opt/src

‎dockerfiles/Dockerfile.docs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
FROM python:3.8-slim
2+
3+
# build-essential is required to build a wheel for ciso8601
4+
RUN apt update && apt install -y build-essential
5+
6+
RUN python -m pip install --upgrade pip
7+
RUN python -m pip install mkdocs mkdocs-material pdocs
8+
9+
COPY . /opt/src
10+
11+
WORKDIR /opt/src
12+
13+
RUN python -m pip install \
14+
stac_fastapi/core \
15+
stac_fastapi/elasticsearch \
16+
stac_fastapi/opensearch
17+
18+
CMD ["pdocs", \
19+
"as_markdown", \
20+
"--output_dir", \
21+
"docs/src/api/", \
22+
"--exclude_source", \
23+
"--overwrite", \
24+
"stac_fastapi"]

‎docs/mkdocs.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
site_name: stac-fastapi-elasticsearch-opensearch
2+
site_description: STAC FastAPI Elasticsearch and Opensearch backends.
3+
4+
# Repository
5+
repo_name: "stac-utils/stac-fastapi-elasticsearch-opensearch"
6+
repo_url: "https://github.com/stac-utils/stac-fastapi-elasticsearch-opensearch"
7+
edit_uri: "blob/main/docs/src/"
8+
9+
docs_dir: 'src'
10+
site_dir: 'build'
11+
12+
# Social links
13+
extra:
14+
social:
15+
- icon: "fontawesome/brands/github"
16+
link: "https://github.com/stac-utils"
17+
18+
# Layout
19+
nav:
20+
- Home: "index.md"
21+
- Tips and Tricks: tips-and-tricks.md
22+
- API:
23+
- stac_fastapi.elasticsearch:
24+
- app: api/stac_fastapi/elasticsearch/app.md
25+
- index: api/stac_fastapi/elasticsearch/index.md
26+
- config: api/stac_fastapi/elasticsearch/config.md
27+
- database_logic: api/stac_fastapi/elasticsearch/database_logic.md
28+
- index: api/stac_fastapi/elasticsearch/index.md
29+
- version: api/stac_fastapi/elasticsearch/version.md
30+
- stac_fastapi.opensearch:
31+
- app: api/stac_fastapi/opensearch/app.md
32+
- index: api/stac_fastapi/opensearch/index.md
33+
- config: api/stac_fastapi/opensearch/config.md
34+
- database_logic: api/stac_fastapi/opensearch/database_logic.md
35+
- index: api/stac_fastapi/opensearch/index.md
36+
- version: api/stac_fastapi/opensearch/version.md
37+
- stac_fastapi.core:
38+
- index: api/stac_fastapi/core/index.md
39+
- base_database_logic: api/stac_fastapi/core/base_database_logic.md
40+
- base_settings: api/stac_fastapi/core/base_settings.md
41+
- core: api/stac_fastapi/core/core.md
42+
- datetime_utils: api/stac_fastapi/core/datetime_utils.md
43+
- extensions:
44+
- module: api/stac_fastapi/core/extensions/index.md
45+
- filter: api/stac_fastapi/core/extensions/filter.md
46+
- query: api/stac_fastapi/core/extensions/query.md
47+
- models:
48+
- module: api/stac_fastapi/core/models/index.md
49+
- links: api/stac_fastapi/core/models/links.md
50+
- search: api/stac_fastapi/core/models/search.md
51+
- serializers: api/stac_fastapi/core/serializers.md
52+
- session: api/stac_fastapi/core/session.md
53+
- utilities: api/stac_fastapi/core/utilities.md
54+
- version: api/stac_fastapi/core/version.md
55+
- Development - Contributing: "contributing.md"
56+
- Release Notes: "release-notes.md"
57+
58+
plugins:
59+
- search
60+
61+
# Theme
62+
theme:
63+
icon:
64+
logo: "material/home"
65+
repo: "fontawesome/brands/github"
66+
name: "material"
67+
language: "en"
68+
font:
69+
text: "Nunito Sans"
70+
code: "Fira Code"
71+
72+
extra_css:
73+
- stylesheets/extra.css
74+
75+
# These extensions are chosen to be a superset of Pandoc's Markdown.
76+
# This way, I can write in Pandoc's Markdown and have it be supported here.
77+
# https://pandoc.org/MANUAL.html
78+
markdown_extensions:
79+
- admonition
80+
- attr_list
81+
- codehilite:
82+
guess_lang: false
83+
- def_list
84+
- footnotes
85+
- pymdownx.arithmatex
86+
- pymdownx.betterem
87+
- pymdownx.caret:
88+
insert: false
89+
- pymdownx.details
90+
- pymdownx.emoji
91+
- pymdownx.escapeall:
92+
hardbreak: true
93+
nbsp: true
94+
- pymdownx.magiclink:
95+
hide_protocol: true
96+
repo_url_shortener: true
97+
- pymdownx.smartsymbols
98+
- pymdownx.superfences
99+
- pymdownx.tasklist:
100+
custom_checkbox: true
101+
- pymdownx.tilde
102+
- toc:
103+
permalink: true

‎docs/src/contributing.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../CONTRIBUTING.md

0 commit comments

Comments
 (0)