Merge branch 'issue142-docs-sphinx'

.github/workflows/docs2ghpages.yml

@@ -0,0 +1,45 @@
+name: Build docs and push to GitHub Pages
+
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.12
+
+    - name: Install dependencies (including Sphinx)
+      run: python -m pip install -r docs/requirements.txt
+
+    - name: Sphinx build
+      # Build HTML documentation from sources under `docs` to `build` folder.
+      run: python -m sphinx -b html docs build
+
+    - name: Commit documentation in gh-pages branch
+      # Store documentation in a temporary one-commit git repo.
+      run: |
+        cd build
+        git init -b gh-pages
+        touch .nojekyll
+        git config --local user.name "GitHub Actions Bot"
+        git config --local user.email "[email protected]"
+        git add .
+        git commit -m "Update documentation"
+
+    - name: Push gh-pages branch
+      # Push from the temporary repo to the `gh-pages` branch of your repo.
+      # Warning: this will overwrite any existing content and history
+      # of the `gh-pages` branch.
+      run: |
+        cd build
+        git push --force "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}" gh-pages
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 The format is roughly based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## 0.35.0
+
+- Start with `openeo-aggregator` docs, hosted with GitHub Pages at https://open-eo.github.io/openeo-aggregator/ ([#142](https://github.com/Open-EO/openeo-aggregator/issues/142))
+
 ## 0.34.0
 
 - Also support `job_options_update` to inject job options in synchronous processing requests ([#135](https://github.com/Open-EO/openeo-aggregator/issues/135), eu-cdse/openeo-cdse-infra#114)

docs/.gitignore

@@ -0,0 +1,4 @@
+build/
+_build/
+venv/
+.venv/

docs/conf.py

@@ -0,0 +1,19 @@
+project = "openEO Aggregator"
+
+extensions = [
+    "myst_parser",
+    "sphinx_design",
+    "sphinxcontrib.mermaid",
+]
+myst_enable_extensions = ["colon_fence"]
+
+root_doc = "index"
+html_theme = "furo"
+
+
+exclude_patterns = [
+    "_build",
+    "build",
+    ".venv",
+    "venv",
+]

docs/README.md → docs/index.md

@@ -5,7 +5,21 @@ The openEO Aggregator is a software component to group multiple openEO back-ends
 into a unified, federated openEO processing platform.
 
 
-## Background: openEO
+```{mermaid}
+flowchart LR
+
+U("👤 User") --> A("openEO Aggregator")
+
+subgraph federation ["Federated openEO Processing"]
+
+    A --> B1("openEO Back-end 1")
+    A --> B2("openEO Back-end 2")
+    A --> B3("openEO Back-end 3")
+end
+```
+
+
+## Core openEO API
 
 The [openEO API](https://openeo.org/) is an open, standardized API for Earth Observation data processing,
 connecting openEO-capable clients at the user side with openEO-capable back-ends at the (cloud) processing side.
@@ -33,3 +47,12 @@ including, but not limited to:
 - unified listing of batch jobs of a user across multiple back-ends
 - dispatching of simple processing requests (both for synchronous processing and batch jobs) to the appropriate back-end
 - handling of more complex processing requests that require data from multiple back-ends
+
+
+
+```{toctree}
+:hidden:
+pages/installation.md
+pages/configuration.md
+pages/usage.md
+```

docs/pages/configuration.md

@@ -0,0 +1,13 @@
+
+
+# Configuration
+
+
+
+The openEO Aggregator can be configured through a `AggregatorBackendConfig` class
+
+
+
+## Gunicorn configuration
+
+TODO

docs/pages/installation.md

@@ -0,0 +1,13 @@
+
+# Installation
+
+The openEO Aggregator can be installed via pip:
+
+```shell
+python -m pip install openeo-aggregator
+```
+
+
+## Requirements
+
+- Optional: a Zookeeper cluster for caching and partitioned job db

docs/pages/usage.md

@@ -0,0 +1,16 @@
+
+# Usage
+
+## Run with Flask in development mode
+
+```shell
+export FLASK_APP='openeo_aggregator.app:create_app()'
+export FLASK_ENV=development
+flask run
+```
+
+## Run with Gunicorn
+
+```shell
+gunicorn 'openeo_aggregator.app:create_app()'
+```

docs/requirements.txt

@@ -0,0 +1,5 @@
+Sphinx~=7.3.7
+myst-parser~=3.0.1
+sphinx-design~=0.6.0
+furo~=2024.5.6
+sphinxcontrib-mermaid~=0.9.2

src/openeo_aggregator/about.py

@@ -2,7 +2,7 @@
 import sys
 from typing import Optional
 
-__version__ = "0.34.2a1"
+__version__ = "0.35.0a1"
 
 
 def log_version_info(logger: Optional[logging.Logger] = None):