openEO documentation

Source repository for the openEO documentation site. The site documents the openEO API, processes, clients, backends, examples, and project news.

The website is built with Quarto and published through GitHub Pages.

Prerequisites

• Quarto
• Python 3.11 or later (GitHub Actions uses Python 3.11)
• Git, including submodule support

Get started

Clone the repository together with its example-notebook submodule:

git clone --recurse-submodules https://github.com/Open-EO/openeo-docs.git
cd openeo-docs
pip install -r requirements.txt

If the repository was already cloned without submodules, initialise them with:

git submodule update --init --recursive

Preview locally

Run:

quarto preview

The local preview is configured to use port 5555 (see project.preview.port in _quarto.yml), so it opens at http://localhost:5555. Quarto watches the source files and rebuilds the pages when they change. Use Ctrl+C to stop it. Please feel free to change the port if needed.

5555 is for hahahaha fun purposes, hehehehe

To produce a complete local build without the preview server, run:

quarto render

The generated website is written to _site/, which is not committed.

Content and structure

• index.qmd – homepage
• documentation/ – user documentation and cookbook content
• examples.qmd – categorized, filterable catalog of the community example notebooks
• news/, events/, and meetings.qmd – project communication
• custom.css and custom.html – shared presentation and browser behaviour
• _quarto.yml – Quarto site configuration, navigation, rendering rules, and pre-render hooks
• news/images/ – shared image assets, including the navbar logo
• images/notebook_previews/ – static preview images extracted from example notebooks, used by examples.qmd

Use .qmd files for new Quarto content. Quarto resolves relative links and images from the location of the source file.

Client examples submodule

client_examples/openeo-community-examples is a Git submodule pointing to the openEO community examples repository. It contains notebooks and supporting material used by the documentation.

The submodule is excluded from Quarto's normal render input, except for the curated notebooks under python/**, which Quarto renders to standalone HTML pages (using each notebook's existing stored outputs, without re-executing any code) so that entries in examples.qmd link to a rendered page instead of a raw .ipynb file. Update an example in its own repository, then update the submodule pointer in this repository:

cd client_examples/openeo-community-examples
git pull origin main
cd ../..
git add client_examples/openeo-community-examples

Commit the updated pointer together with any documentation links that use the example.

Notebook examples catalog

examples.qmd lists every notebook under client_examples/openeo-community-examples/python/, grouped into categories (e.g. Data Access, Preprocessing, SAR Processing, Machine Learning) with filter-ui/sort-ui/categories enabled. Several documentation pages under documentation/ also link directly to the most relevant notebook for a given process (e.g. temporal_operations.qmd links to the anomaly-detection notebooks).

Most entries reference a static preview image under images/notebook_previews/, extracted from each notebook's own stored output (a couple of entries instead reference an image hosted by the community-examples project's own site). Re-generate these previews after updating the submodule with:

python py_scripts/extract_notebook_previews.py

Generated version and Hub data

Before every Quarto render, py_scripts/update_api_version.py fetches:

• the latest openEO API release;
• the backend count from the openEO Hub; and
• the process count from the official openEO process catalogue.

It writes the generated values to _variables.yml and _data/_variables.yml. These values are used by the site, for example on the homepage. A render therefore needs internet access to these services.

Image checking

py_scripts/check_images.py runs before Quarto renders. It checks local image references in Quarto/Markdown sources, notebooks, and CSS and prints warnings for missing files. External URLs and data URLs are skipped.

Run it directly with:

python py_scripts/check_images.py

Use strict mode when you want missing local images to fail the command:

python py_scripts/check_images.py --strict
# or
$env:IMAGE_CHECK_STRICT = '1'
python py_scripts/check_images.py

JupyterLite showcase

The GitHub Pages workflows build an openEO-hosted JupyterLite site at:

https://open-eo.github.io/openeo-docs/jupyterlite/

Every notebook under client_examples/openeo-community-examples/python/ is bundled into the showcase (copied in during the CI build, see .github/workflows/*.yml). It is intended for exploring the notebook interface; helper files, datasets, and scientific dependencies are not preinstalled, and cloud-authenticated workflows are not expected to run end-to-end there. See jupyterlite/README.md for details.

Publishing

GitHub Actions handles site publication:

• pushes to main render Quarto, build JupyterLite, and deploy the site to GitHub Pages;
• pushes to staging render and archive a staging build under the gh-pages branch; and
• pull requests receive archived previews under gh-pages/previews/.

The relevant workflow files are in .github/workflows/. Do not commit _site/ or generated JupyterLite content.

Contributing

Keep changes focused, use relative links for repository content, and run quarto preview or quarto render before opening a pull request. If you change an image reference, run the image checker and ensure it points to an existing local asset.