Merge pull request #108 from developmentseed/refactorDocs

✨ refactor docs

Author: vincentsarago

CONTRIBUTING.md

@@ -14,11 +14,13 @@ python -m pip install --upgrade virtualenv
 virtualenv .venv
 source .venv/bin/activate
 
-# Install eoapi modules
+# Install eoapi module
 python -m pip install "psycopg[binary,pool]"
-python -m pip install -e runtime/eoapi/raster["test"] -e runtime/eoapi/stac["test"] -e runtime/eoapi/vector["test"]
+python -m pip install -e runtime/eoapi/raster["test"] # or -e runtime/eoapi/stac["test"]  | -e runtime/eoapi/vector["test"]
 ```
 
+Note: services might have incompatible dependencies which you can resolve by using virtual environnement per service
+
 **pre-commit**
 
 This repo is set to use `pre-commit` to run *isort*, *ruff*, *pydocstring*, *black* ("uncompromising Python code formatter") and mypy when committing new code.

README.md

@@ -33,40 +33,6 @@
 
 - **OGC Features and Vector Tiles** API built on top of [https://github.com/developmentseed/tipg](https://github.com/developmentseed/tipg)
 
----
-
-## Why should you use `eoAPI`
-
-- **Focus on your use case:** `eoAPI` is used for large-scale data processing, building geographic information systems (GIS), creating real-time data applications, climate research and environmental monitoring, machine learning model training, and more.
-
-- **Unified Repository:** `eoAPI` provides a single, unified repository to several state-of-the-art Earth Observation (EO) data services, including Metadata search (STAC), Raster, and Vector services. This can simplify the process of accessing and working with these services.
-
-- **Interoperability:** `eoAPI` is designed to enable interoperability among its included services. This can make building complex applications that leverage different types of EO data easier.
-
-- **Open Source and Community Support:** As an open-source project, `eoAPI` allows developers to inspect its code, contribute to its development, and use it as a base for custom solutions. It also benefits from the support and innovation of a community of developers and EO data users.
-
-- **Scalability and Flexibility:** Each service in `eoAPI` can be used or deployed independently, which provides a lot of flexibility. If a developer's application only requires one or two of eoAPI's services, they don't need to deploy the entire suite.
-
-- **Facilitate Earth Observation Tasks:** `eoAPI` includes specialized tools for working with EO data, such as dynamic tiling, metadata searching, and features/vector tiles API. These can significantly facilitate EO data processing, analysis, and visualization.
-
-- **Ease of Deployment:** `eoAPI` supports containerized deployment using Docker, making it easier to set up, scale, and maintain applications built on it. Spin up the demo locally and start experimenting in minutes.
-
----
-
-## Services Overview
-
-
-- **STAC Metadata**: Built with [stac-fastapi.pgstac](https://github.com/stac-utils/stac-fastapi) and extended with a custom extension to connect it to **`TiTiler`** and a **[Search Viewer](http://localhost:8081/index.html)**. See [docs](http://localhost:8081/docs) for API details.
-
-- **Raster Tiles**: Built with [titiler-pgstac](https://github.com/stac-utils/titiler-pgstac) and [pgstac](https://github.com/stac-utils/pgstac) to enable large scale mosaic based on results of STAC searches queries. See [docs](http://localhost:8082/docs) for API details.
-
-- **OGC Features & Vector Tiles**: Built with [tipg](https://github.com/developmentseed/tipg) to create a lightweight OGC Features and Tiles API with a PostGIS database. See [docs](http://localhost:8083/api.html) for API details.
-
-See [service details](./docs/src/services-details.md) for more information.
-
-*Note: The documentation links referenced require lauching the application with `docker-compose` or another deployment*.
-
----
 
 ## Getting started
 
@@ -90,12 +56,9 @@ export DATABASE_URL=postgresql://username:password@0.0.0.0:5439/postgis  # Conne
 .venv/bin/uvicorn eoapi.{SERVICE}.app:app --port 8000 --reload
 ```
 
-Note: services might have incompatible dependencies which you can resolve by using virtual environement per service
+Note: services might have incompatible dependencies which you can resolve by using virtual environnement per service
 
 ---
-## Deployment
-
-See [DEPLOYMENT.md](https://github.com/developmentseed/eoAPI/blob/main/infrastructure/DEPLOYMENT.md)
 
 ## Contribution & Development
 

docs/mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: eoAPI
+site_name: The Earth Observation API
 site_description: Create a full Earth Observation API with Metadata, Raster and Vector services.
 
 docs_dir: 'src'
@@ -17,20 +17,24 @@ extra:
       link: "https://medium.com/devseed"
 
 nav:
-  - Readme: "index.md"
+  - Home: "index.md"
+  - Intro: "intro.md"
+  - Services: "services.md"
   - Development - Contributing: "contributing.md"
-  - Release Notes: "release-notes.md"
-  - Services Details: "services-details.md"
   - Deployment: "deployment.md"
 
 plugins:
   - search
 
 theme:
   name: material
+  custom_dir: src/overrides/
   palette:
-    primary: indigo
+    primary: black
     scheme: default
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
   favicon: img/favicon.ico
   logo: img/logo.png
 

docs/src/contributing.md

@@ -0,0 +1,34 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+Issues and pull requests are more than welcome: https://github.com/developmentseed/eoAPI/issues
+
+**dev install**
+
+```bash
+# Download the code
+git clone https://github.com/developmentseed/eoAPI.git
+cd eoAPI
+
+# Create a virtual environment
+python -m pip install --upgrade virtualenv
+virtualenv .venv
+source .venv/bin/activate
+
+# Install eoapi module
+python -m pip install "psycopg[binary,pool]"
+python -m pip install -e runtime/eoapi/raster["test"] # or -e runtime/eoapi/stac["test"]  | -e runtime/eoapi/vector["test"]
+```
+
+Note: services might have incompatible dependencies which you can resolve by using virtual environnement per service
+
+**pre-commit**
+
+This repo is set to use `pre-commit` to run *isort*, *ruff*, *pydocstring*, *black* ("uncompromising Python code formatter") and mypy when committing new code.
+
+```bash
+$ pre-commit install
+```

docs/src/contributing.md

@@ -0,0 +1,87 @@
+---
+hide:
+  - navigation
+---
+
+## AWS (Lambda)
+
+An example of Cloud Stack is available for AWS (RDS for the database and Lambda for the APIs)
+
+The stack is deployed by the [AWS CDK](https://aws.amazon.com/cdk/) utility. Under the hood, CDK will create the deployment packages required for AWS Lambda, upload it to AWS, and handle the creation of the Lambda and API Gateway resources.
+
+The example commands here will deploy a CloudFormation stack called `eoAPI-staging`.
+
+1. Clone the `eoapi` repo and install dependencies
+    ```bash
+    # Download eoapi repo
+    git clone https://github.com/developmentseed/eoapi.git
+
+    # Create a virtual environment
+    python -m pip install --upgrade virtualenv
+    virtualenv infrastructure/aws/.venv
+    source infrastructure/aws/.venv/bin/activate
+
+    # install cdk dependencies
+    python -m pip install -r infrastructure/aws/requirements-cdk.txt
+    ```
+
+2. Install node dependency - requires node version 14+
+    ```bash
+    npm --prefix infrastructure/aws install
+    ```
+
+3. Update settings
+
+    Set environment variable or hard code in `infrastructure/aws/.env` file (e.g `CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1`).
+
+    **Important**:
+
+      - `CDK_EOAPI_DB_PGSTAC_VERSION` is a required env (see https://github.com/stac-utils/pgstac/tags for the latest version)
+
+      - You can choose which functions to deploy by setting `CDK_EOAPI_FUNCTIONS` env (e.g `CDK_EOAPI_FUNCTIONS='["stac","raster","vector"]'`)
+
+
+4. Install CDK and connect to your AWS account. This step is only necessary once per AWS account. The environment variable `CDK_EOAPI_STAGE` determines the name of the stack
+(e.g. eoAPI-staging or eoAPI-production)
+    ```bash
+    # Deploy the CDK toolkit stack into an AWS environment.
+    CDK_EOAPI_STAGE=staging \
+    CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1 \
+    npm --prefix infrastructure/aws run cdk -- bootstrap
+
+    # or to a specific region
+    AWS_DEFAULT_REGION=us-west-2 \
+    AWS_REGION=us-west-2 \
+    CDK_EOAPI_STAGE=staging \
+    CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1 \
+    npm --prefix infrastructure/aws run cdk -- bootstrap
+    ```
+
+5. Pre-Generate CFN template
+
+    ```bash
+    CDK_EOAPI_STAGE=staging \
+    CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1 \
+    npm --prefix infrastructure/aws run cdk -- synth  # Synthesizes and prints the CloudFormation template for this stack
+    ```
+
+6. Deploy
+
+    ```bash
+    CDK_EOAPI_STAGE=staging \
+    CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1 \
+    npm --prefix infrastructure/aws run cdk -- deploy eoAPI-staging
+
+    # Deploy in specific region
+    AWS_DEFAULT_REGION=eu-central-1 \
+    AWS_REGION=eu-central-1 \
+    CDK_EOAPI_STAGE=staging \
+    CDK_EOAPI_DB_PGSTAC_VERSION=0.7.1 \
+    npm --prefix infrastructure/aws run cdk -- deploy eoapi-staging --profile {my-aws-profile}
+    ```
+
+If you get an error saying that the max VPC's has been reached, this means that you have hit the limit for the amount of VPCs per unique AWS account and region combination. You can change the AWS region to a region that has less VPCs and deploy again to fix this.
+
+## K8S
+
+A Kubernetes chart is currently being developed at https://github.com/developmentseed/k8s-eoapi