From 3a3c51c931883ef0e7f2f0b55b174e7df78bcaad Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 12 Jun 2024 16:13:39 +0200 Subject: [PATCH 1/4] Issue #142 Initial Sphinx+MyST doc setup --- docs/.gitignore | 4 ++++ docs/conf.py | 19 +++++++++++++++++++ docs/{README.md => index.md} | 25 ++++++++++++++++++++++++- docs/pages/configuration.md | 13 +++++++++++++ docs/pages/installation.md | 13 +++++++++++++ docs/pages/usage.md | 16 ++++++++++++++++ docs/requirements.txt | 5 +++++ 7 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 docs/.gitignore create mode 100644 docs/conf.py rename docs/{README.md => index.md} (85%) create mode 100644 docs/pages/configuration.md create mode 100644 docs/pages/installation.md create mode 100644 docs/pages/usage.md create mode 100644 docs/requirements.txt diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..26919e0 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +build/ +_build/ +venv/ +.venv/ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..14010e4 --- /dev/null +++ b/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", +] diff --git a/docs/README.md b/docs/index.md similarity index 85% rename from docs/README.md rename to docs/index.md index 1989c83..1d99811 100644 --- a/docs/README.md +++ b/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 +``` diff --git a/docs/pages/configuration.md b/docs/pages/configuration.md new file mode 100644 index 0000000..1b6af9d --- /dev/null +++ b/docs/pages/configuration.md @@ -0,0 +1,13 @@ + + +# Configuration + + + +The openEO Aggregator can be configured through a `AggregatorBackendConfig` class + + + +## Gunicorn configuration + +TODO diff --git a/docs/pages/installation.md b/docs/pages/installation.md new file mode 100644 index 0000000..b9eae91 --- /dev/null +++ b/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 diff --git a/docs/pages/usage.md b/docs/pages/usage.md new file mode 100644 index 0000000..be3295f --- /dev/null +++ b/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()' +``` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..6dd68ce --- /dev/null +++ b/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 From 7f6d3ee81d56358b94db2bb41033f573cbd72dea Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 12 Jun 2024 16:32:19 +0200 Subject: [PATCH 2/4] Issue #142 initial GitHub workflow for doc build+publish --- .github/workflows/docs2ghpages.yml | 42 ++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/docs2ghpages.yml diff --git a/.github/workflows/docs2ghpages.yml b/.github/workflows/docs2ghpages.yml new file mode 100644 index 0000000..f160130 --- /dev/null +++ b/.github/workflows/docs2ghpages.yml @@ -0,0 +1,42 @@ +name: Build docs and push to GitHub Pages + +on: push + +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 "actions@github.com" + 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 }} From d2052d6643d678393ae9c37d877a63a7f6a5cae1 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 12 Jun 2024 16:40:33 +0200 Subject: [PATCH 3/4] Issue #142 only build docs on push of master branch --- .github/workflows/docs2ghpages.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs2ghpages.yml b/.github/workflows/docs2ghpages.yml index f160130..1d3572d 100644 --- a/.github/workflows/docs2ghpages.yml +++ b/.github/workflows/docs2ghpages.yml @@ -1,6 +1,9 @@ name: Build docs and push to GitHub Pages -on: push + +on: + push: + branches: [ master ] jobs: build: From 2c96297e155bed9cda074b9dd3d5fcc7902ebe3f Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 12 Jun 2024 16:43:03 +0200 Subject: [PATCH 4/4] Issue #142 add changelog entry --- CHANGELOG.md | 4 ++++ src/openeo_aggregator/about.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 008961b..cfc086e 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/src/openeo_aggregator/about.py b/src/openeo_aggregator/about.py index 3e4276f..39058d7 100644 --- a/src/openeo_aggregator/about.py +++ b/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):