Add mkdocs

.github/workflows/lint.yml

@@ -1,6 +1,6 @@
 name: Lint
 
-on: [pull_request, push]
+on: [pull_request]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

.github/workflows/pre-commit.yml

@@ -1,6 +1,6 @@
 name: Pre-commit
 
-on: [pull_request, push]
+on: [pull_request]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

.github/workflows/publish-gh-pages.yml

@@ -0,0 +1,52 @@
+name: Publish gh-pages
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  Publish-gh-pages:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        run: |
+          pip install poetry
+
+      - name: Cache Poetry virtualenv and dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/pypoetry
+            ~/.cache/pip
+          key: poetry-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+          restore-keys: |
+            poetry-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          make install
+
+      - name: Run mkdocs deploy
+        run: |
+          poetry run mkdocs gh-deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -1,6 +1,6 @@
 name: Test
 
-on: [pull_request, push]
+on: [pull_request]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

.pre-commit-config.yaml

@@ -12,7 +12,6 @@ repos:
       - id: debug-statements
       - id: check-builtin-literals
       - id: check-case-conflict
-      - id: check-docstring-first
       - id: detect-private-key
       - id: check-added-large-files
         args: ["--maxkb=5000"]

Makefile.targets

@@ -5,4 +5,34 @@
 
 .PHONY: test-notebooks
 test-notebooks: ## Execute test notebooks using pytest and nbval
-	$(ENV_COMMAND_TOOL) nox -s test_nb
+	$(ENV_COMMAND_TOOL) nox -s test_nb
+
+## -- Docs targets -------------------------------------------------------------------------------------------------- ##
+.PHONY: preview-docs
+preview-docs: ## Preview the documentation site locally
+	@poetry run mkdocs serve -a 0.0.0.0:7000
+
+
+.PHONY: build-docs
+build-docs: ## Build the documentation files locally
+	@poetry run mkdocs build
+
+.PHONY: deploy-docs
+deploy-docs: ## Publish and deploy the documentation to the live Github page
+	@echo""; \
+	echo -e "\e[1;39;41m-- WARNING --\e[0m This command will deploy all current changes to the live Github page - Making it publicly available"; \
+	echo""; \
+	echo -n "Would you like to deploys the docs? [Y/n]: "; \
+	read ans; \
+	case $$ans in \
+		[Yy]*) \
+			echo""; \
+			poetry run mkdocs gh-deploy; \
+			echo""; \
+			;; \
+		*) \
+			echo""; \
+			echo "Skipping publication to Github Pages."; \
+			echo " "; \
+			;; \
+	esac; \

docs/mkdocs/index.md

@@ -0,0 +1,26 @@
+# Geospatial tools
+
+## Description
+
+This repository is a collection of tools and scripts for geospatial use cases.
+
+For more detailed information on how to install, configure and develop a project 
+using this repository, please refer yourself to the project's 
+[README](https://github.com/RolnickLab/geospatial-tools/blob/main/README.md)
+
+## Requirements
+
+This project has only been tested in a Linux (Debian based) environment and assumes
+some basic tools for development are already installed.
+
+The project uses a Makefile to automate most operations. If `make` is available on your
+machine there's a good chance this will work.
+
+## Python Version
+
+This project uses Python version 3.11
+
+## Build Tool
+
+This project uses [`poetry`](https://python-poetry.org/) as a build tool. Using a build tool has the advantage of
+streamlining script use as well as fix path issues related to imports.

docs/mkdocs/scripts/gen_ref_pages.py

@@ -0,0 +1,39 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent.parent.parent
+src = root / "geospatial_tools"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if not parts:
+        continue
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        if not parts:
+            continue
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/mkdocs/sections/dev-guide/developer-guide.md

@@ -0,0 +1 @@
+# Dev Guide

docs/mkdocs/sections/user-guide/notebook-examples.md

@@ -0,0 +1,6 @@
+# Notebook Examples
+
+There are a few notebook examples available.
+
+- [How to use STAC API](https://github.com/RolnickLab/geospatial-tools/blob/main/notebooks/stac_api_tools.ipynb)
+- [Exploring Sentinel 2 data from Planetary Computer](https://github.com/RolnickLab/geospatial-tools/blob/main/notebooks/planetary_computer_sentinel2_exploration.ipynb)

geospatial_tools/download.py

@@ -11,6 +11,17 @@
 def _download_from_link(
     target_download: str, output_name: str = None, output_directory: str | Path = DATA_DIR
 ) -> list[str | Path]:
+    """
+
+    Args:
+      target_download: str:
+      output_name: str:  (Default value = None)
+      output_directory: str | Path:  (Default value = DATA_DIR)
+
+    Returns:
+
+
+    """
     file_configs = get_yaml_config("data_file_links")
     key = target_download
     url = file_configs[key]["url"]
@@ -28,16 +39,13 @@ def download_usa_polygon(output_name: str = USA_POLYGON, output_directory: str |
     """
     Download USA polygon file.
 
-    Parameters
-    ----------
-    output_name
-        What name to give to downloaded file
-    output_directory
-        Where to save the downloaded file
+    Args:
+      output_name: What name to give to downloaded file
+      output_directory: Where to save the downloaded file
+      output_name: str:  (Default value = USA_POLYGON)
+      output_directory: str | Path:  (Default value = DATA_DIR)
 
-    Returns
-    -------
-    List of output path to downloaded file
+    Returns:
     """
     file_list = _download_from_link(
         target_download=USA_POLYGON, output_name=output_name, output_directory=output_directory
@@ -51,16 +59,13 @@ def download_s2_tiling_grid(
     """
     " Download Sentinel 2 tiling grid file.
 
-    Parameters
-    ----------
-    output_name
-        What name to give to downloaded file
-    output_directory
-        Where to save the downloaded file
+    Args:
+      output_name: What name to give to downloaded file
+      output_directory: Where to save the downloaded file
+      output_name: str:  (Default value = SENTINEL_2_TILLING_GRID)
+      output_directory: str | Path:  (Default value = DATA_DIR)
 
-    Returns
-    -------
-    List of output path to downloaded file
+    Returns:
     """
     file_list = _download_from_link(
         target_download=SENTINEL_2_TILLING_GRID, output_name=output_name, output_directory=output_directory

geospatial_tools/geotools_types.py

@@ -1,5 +1,8 @@
 """This module contains constants and functions pertaining to data types."""
 
+from datetime import datetime
+from typing import Iterator, Union
+
 from shapely.geometry import (
     GeometryCollection,
     LineString,
@@ -11,4 +14,17 @@
 )
 
 BBoxLike = tuple[float, float, float, float]
-IntersectsLike = Point | Polygon | LineString | MultiPolygon | MultiPoint | MultiLineString | GeometryCollection
+"""BBox like tuple structure used for type checking."""
+
+IntersectsLike = Union[Point, Polygon, LineString, MultiPolygon, MultiPoint, MultiLineString, GeometryCollection]
+"""Intersect-like union of types used for type checking."""
+
+DateLike = Union[
+    datetime,
+    str,
+    None,
+    tuple[Union[datetime, str, None], Union[datetime, str, None]],
+    list[Union[datetime, str, None]],
+    Iterator[Union[datetime, str, None]],
+]
+"""Date-like union of types used for type checking."""