Initial commit

Author: ttuff

.github/workflows/build-and-push-jupyterlab-image.yml

@@ -0,0 +1,44 @@
+name: build-and-push-jupyterlab-image
+
+on:
+  workflow_dispatch:  # This allows you to manually trigger the action from GitHub UI.
+
+jobs:
+  
+  build:
+    runs-on: ubuntu-latest
+    
+    steps:
+    
+      - name: Checkout
+        uses: actions/checkout@v4
+      
+      - name: Set up Docker Buildx
+        id: buildx
+        uses: docker/setup-buildx-action@v3
+            
+      - name: Login to dockerhub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
+      - name: Get lowercase repo name (for dynamic tags)
+        id: repo_name
+        run: |
+          lowercase_name=$(echo ${{ github.event.repository.name }} | tr '[:upper:]' '[:lower:]')
+          echo "repo_name=${lowercase_name}" >> "$GITHUB_OUTPUT"
+        
+      - name: Build and push latest
+        id: docker_build_jupyterlab
+        uses: docker/build-push-action@v5
+        with:
+          context: containers/jupyterlab
+          file: containers/jupyterlab/Dockerfile
+          builder: ${{ steps.buildx.outputs.name }}
+          push: true
+          tags: |
+            esiil/${{ steps.repo_name.outputs.repo_name }}_jupyterlab:latest
+     
+      - name: Image digest
+        run: echo ${{ steps.docker_build_jupyterlab.outputs.digest }}

.github/workflows/fetch-template.yml

@@ -0,0 +1,34 @@
+name: Sync with Template Repository
+
+on:
+    workflow_dispatch:
+
+jobs:
+  sync_template:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout main repository
+      uses: actions/checkout@v4
+
+    - name: Configure Git for merge
+      run: |
+          git config --global user.name "github-actions" 
+          git config --global user.email "actions@users.noreply.github.com"
+    
+    - name: Fetch template repository
+      run: git fetch --no-tags --no-recurse-submodules https://github.com/CU-ESIIL/Working_group_OASIS.git +refs/heads/*:refs/remotes/template/*
+
+    - name: Merge changes from template repository
+      run: |
+        git merge --no-commit --no-ff --allow-unrelated-histories template/main || true
+        git checkout --ours .
+        git add .
+        
+    - name: Commit changes
+      run: git commit -am "Merge changes from template repository"
+
+    - name: Push changes
+      uses: ad-m/github-push-action@v0.6.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/pages.yml

@@ -0,0 +1,74 @@
+name: Deploy MkDocs site to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then
+            python -m pip install -r requirements.txt
+          else
+            python -m pip install mkdocs
+          fi
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict --clean --site-dir dist
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+        continue-on-error: true
+
+      - name: Verify Pages is enabled
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          api_url="https://api.github.com/repos/${GITHUB_REPOSITORY}/pages"
+          status="$(curl -sS -H "Authorization: Bearer ${GITHUB_TOKEN}" -H "Accept: application/vnd.github+json" -o /tmp/pages-response.json -w "%{http_code}" "${api_url}")"
+          if [ "${status}" = "404" ]; then
+            echo "::error::Enable GitHub Pages: Settings → Pages → Source = GitHub Actions and Settings → Actions → Workflow permissions = Read and write."
+            exit 1
+          elif [ "${status}" != "200" ]; then
+            echo "::error::Failed to verify GitHub Pages (HTTP ${status})."
+            cat /tmp/pages-response.json
+            exit 1
+          fi
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,51 @@
+# History files
+.Rhistory
+.Rapp.history
+
+# Session Data files
+.RData
+.RDataTmp
+
+# User-specific files
+.Ruserdata
+
+# Example code in package build process
+*-Ex.R
+
+# Output files from R CMD build
+/*.tar.gz
+
+# Output files from R CMD check
+/*.Rcheck/
+
+# RStudio files
+.Rproj.user/
+
+# produced vignettes
+vignettes/*.html
+vignettes/*.pdf
+
+# OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3
+.httr-oauth
+
+# knitr and R markdown default cache directories
+*_cache/
+/cache/
+
+# Temporary files created by R markdown
+*.utf8.md
+*.knit.md
+
+# R Environment Variables
+.Renviron
+
+
+
+# translation temp files
+po/*~
+
+# RStudio Connect folder
+rsconnect/
+
+# macOS
+.DS_Store

AGENTS.md

@@ -0,0 +1,59 @@
+# AGENTS.md
+
+## Core Operating Contract
+- Treat this repository as the source of truth.
+- Treat the website as a rendered view of repository state.
+- Prefer small, additive, traceable edits.
+- Keep documentation synchronized with code and project structure.
+- Keep the repository minimalist by default.
+
+## Default Workflow
+- Inspect repository structure before editing.
+- Make the smallest diff that solves the request.
+- Update related docs when behavior, workflows, or outputs change.
+- Update changelog, dev log, or equivalent history files for meaningful changes.
+- Preserve existing structure and historical context.
+- Do not perform destructive rewrites unless explicitly requested.
+
+## Documentation and Website Policy
+- Treat `docs/` as project-level documentation and website source.
+- Update docs whenever code, workflows, or outputs change.
+- Amend existing docs when possible; do not replace whole files without need.
+- Preserve navigation, readability, and consistency in website changes.
+- Keep default website behavior clean and minimal unless the user asks for more expressive design.
+
+## Testing Policy
+- Assume `tests/` may exist before a full testing framework is defined.
+- Do not invent domain-specific tests when expected behavior is unclear.
+- Add the smallest meaningful tests when behavior is known.
+- Prefer early-stage checks such as smoke tests, import tests, CLI tests, schema checks, or example-based checks.
+- If tests are deferred, document the gap; do not imply coverage that does not exist.
+
+## Package and Structure Separation Policy
+- Keep website structure and package structure clearly separated.
+- Do not automatically repurpose `docs/` for package-native docs or build artifacts.
+- For Python packaging requests, prefer standard Python layout, typically `src/`.
+- For R packaging requests, follow standard R conventions (`R/`, `man/`, `DESCRIPTION`, `NAMESPACE`, optional `vignettes/`).
+- For other ecosystems, follow ecosystem conventions.
+- If structural conflicts arise, choose a durable long-term structure and document the decision.
+
+## Data Discovery and Data Use Policy
+- Prefer open and FAIR data when possible.
+- Prefer streaming or lazy-access workflows over bulk downloads when feasible.
+- Use standards-based discovery systems (for example STAC) when relevant.
+- When relevant, consider streaming-friendly tooling such as xarray, zarr, GDAL, rasterio, pystac-client, stackstac, gdalcubes, terra, stars, cubo, or equivalent tools.
+- When introducing data, document source, access method, format, license, and citation requirements.
+- Do not silently ingest external data into the project.
+
+## Data Sovereignty and Intellectual Property Policy
+- Consider licensing, copyright, privacy, Indigenous data sovereignty, and related restrictions for all data and content.
+- If rights or permissions are unclear, document uncertainty and avoid assuming open reuse.
+
+## Design and Usability Policy
+- Keep the website simple, readable, and easy to extend by default.
+- When design improvements are requested, prioritize system-level improvements (layout, spacing, typography, hierarchy, navigation, consistency).
+- Do not use scattered one-off styling hacks.
+- If direct site inspection is possible, verify readability, navigation, link integrity, and that docs still reflect repository state.
+
+## Decision Logging
+- Reflect meaningful structural, architectural, documentation, data-source, or design decisions in changelog, dev log, roadmap, or equivalent history files when appropriate.

README.md

@@ -0,0 +1,50 @@
+# Research Project Template
+
+This repository is a **minimal template for research and data science projects** that combine code, documentation, and a project website.
+
+It includes:
+
+* a clean project structure (`src`, `data`, `docs`, `tests`, etc.)
+* a documentation website built with **MkDocs + Material**
+* automatic deployment to **GitHub Pages** using GitHub Actions
+* development history files (changelog, roadmap, dev log)
+* an `AGENTS.md` file with guidance for AI coding agents
+
+The website is built from the `docs/` folder and automatically deployed when changes are pushed.
+
+---
+
+# Enable the Website
+
+After creating a repository from this template you must enable GitHub Pages once.
+
+1. Go to **Settings → Pages**
+2. Under **Build and deployment**, choose
+   **Source: GitHub Actions**
+
+The site will then deploy automatically on push.
+
+Your site will appear at:
+
+```
+https://<your-username>.github.io/<repository-name>/
+```
+
+---
+
+# Preview Locally
+
+```
+pip install mkdocs mkdocs-material
+mkdocs serve
+```
+
+Then open:
+
+```
+http://127.0.0.1:8000
+```
+
+---
+
+Use **"Use this template"** on GitHub to start a new project.