(sedona) branch master updated: [DOCS] Expand info on Makefile, uv, prek and code quality (#3081)

[ji...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git


The following commit(s) were added to refs/heads/master by this push:
     new 47141e2cb7e [DOCS] Expand info on Makefile, uv, prek and code quality (#3081)
47141e2cb7e is described below

commit 47141e2cb7e0e5afa1ddecb9b9e79f0612357111
Author: John Bampton <jb...@users.noreply.github.com>
AuthorDate: Wed Aug 5 04:21:57 2026 +1000

    [DOCS] Expand info on Makefile, uv, prek and code quality (#3081)
---
 .pre-commit-config.yaml | 10 +++----
 Makefile                |  4 +--
 docs/setup/compile.md   | 76 ++++++++++++++++++++++++++++++++++++++-----------
 3 files changed, 67 insertions(+), 23 deletions(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 57ee4d2fbb7..694dae8ddd0 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -341,7 +341,7 @@ repos:
         description: audits Python environments, requirements files and dependency trees for known security vulnerabilities, and can automatically fix them
         args: ['.']
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: dd18dad857d6133e90bbe478f4f2f22ec0030269 # frozen: v22.1.5
+    rev: f4d7745e17a28aad7eed2f4874ca8d1568c11c4c # frozen: v22.1.8
     hooks:
       - id: clang-format
         name: run clang-format
@@ -357,7 +357,7 @@ repos:
         args: ['-c=pyproject.toml', '-r']
         additional_dependencies: ['bandit[toml]']
   - repo: https://github.com/codespell-project/codespell
-    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a # frozen: v2.4.2
+    rev: 57b21406f092110c18776e39b0bda50d37c945c8 # frozen: v2.4.3
     hooks:
       - id: codespell
         name: run codespell
@@ -369,7 +369,7 @@ repos:
         name: run gitleaks
         description: check for secrets with gitleaks
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: 9257c6050c0261b8c57e712f632dc4a8010109a9 # frozen: v1.25.2
+    rev: 451b56af716f9f0d0c2b816503a3fd0cf8b036fa # frozen: v1.29.0
     hooks:
       - id: zizmor
         name: run zizmor
@@ -502,7 +502,7 @@ repos:
         args: [--markdown-linebreak-ext=md]
         exclude: \.Rd$
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: a4d5d37e66ebcd6b3705204a1d6dbb56dea66338 # frozen: v0.49.0
+    rev: 5b5dddc4fb0f83c3ea1fc5616fa63e115dce83e0 # frozen: v0.49.1
     hooks:
       - id: markdownlint
         name: run markdownlint
@@ -512,7 +512,7 @@ repos:
         types: [markdown]
         files: \.md$
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 5030dca3047414c338091455ac41803200ec1f0f # frozen: 0.37.3
+    rev: 6b63472e72e1a91ed8a2f6d483790dfb644fa1d3 # frozen: 0.37.4
     hooks:
       - id: check-citation-file-format
         name: run check-citation-file-format
diff --git a/Makefile b/Makefile
index 50908bb262c..87316a9a0ce 100644
--- a/Makefile
+++ b/Makefile
@@ -61,9 +61,9 @@ sync-no-dev: check-install ## Sync non-development dependencies using uv
 	uv sync --no-dev
 
 update: install
-	prek auto-update
+	prek auto-update --freeze
 
 update-deps: check-install ## Update pre-commit hooks and dependency locks
-	prek auto-update || :
+	prek auto-update --freeze || :
 	uv lock --upgrade
 	uv sync --all-groups
diff --git a/docs/setup/compile.md b/docs/setup/compile.md
index 40634765530..5c981b67fd0 100644
--- a/docs/setup/compile.md
+++ b/docs/setup/compile.md
@@ -159,42 +159,86 @@ uv run mike deploy --update-aliases latest-snapshot -b website -p
 uv run mike serve -b website
 ```
 
-## Code Quality Checks with `prek`, `uv`, and `make`
-
-This guide explains how Apache Sedona manages local code quality checks, formatting, and linting. To ensure a fast and consistent developer experience, we combine **`uv`** (a lightning-fast Python package and environment manager) with **`prek`** (our internal pre-commit wrapper framework) and expose everything via a simple, unified `Makefile`.
+### Compiling via Makefile (Recommended)
 
----
-
-### Prerequisites
+For a streamlined developer experience, a unified `Makefile` is provided to handle local documentation builds automatically.
 
-Before running any checks, ensure you have `uv` installed on your machine. If you don't have it yet, you can install it via the official installer:
+To build and serve the documentation locally using the automated environment pipeline, run:
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
+make docsbuild
 ```
 
-> 💡 **Note:** You do not need to manually install Python virtual environments, `pre-commit`, or `prek`. The `Makefile` handles environment isolation and dependency resolution automatically using `uv`.
+**What this command does behind the scenes:**
+
+1. **Environment Verification:** Validates that `uv` is available on your local path.
+2. **Dependency Syncing:** Runs `uv sync --group docs` (via `make docsinstall`) to set up or synchronize the documentation environment containing MkDocs and compilation dependencies.
+3. **Asset Generation:** Navigates into the `docs-overrides` directory to fetch, build, and bundle required JavaScript and CSS assets via Node/NPM and Gulp workflows.
+4. **MkDocs Compilation:** Compiles the Markdown files in the `docs` directory into a fully optimized, static HTML website based on the configuration inside `mkdocs.yml`.
 
 ---
 
-### The Core Workflow: `uv` + `prek`
+## Code Quality Checks with `prek`, `uv`, and `make`
 
-Our codebase uses `prek` to orchestrate linting and formatting workflows (such as *Black*, *markdownlint*, or *oxipng*).
+This guide explains how Apache Sedona manages local code quality checks, formatting, and linting. To ensure a fast and consistent developer experience, we combine `uv` (a lightning-fast Python package and environment manager) with `prek` (our internal pre-commit wrapper framework) and expose everything via a simple, unified `Makefile`.
 
-Instead of forcing you to activate a virtual environment manually, the `Makefile` uses `uv sync` to build a perfectly isolated environment behind the scenes. When you run any `make check-*` command, it guarantees that `prek` is executed using the exact dependency versions locked in the project.
+### Prerequisites
 
----
+Make sure your machine has `uv` and Python 3.8+ installed before running checks.
 
-### Available Make Commands
+### Core Workflow via Makefile
 
-For maximum convenience, you should interact with `prek` entirely through the following `make` shortcuts:
+The `Makefile` handles environment isolation and dependency resolution automatically using `uv`. For maximum convenience, you should interact with `prek` entirely through the following make shortcuts:
 
 * **`make check-stage`** *Runs checks on staged changes only (Recommended before committing).* Evaluates `prek` only against the files you have explicitly staged using `git add`. It is incredibly fast.
 * **`make check`** *Runs checks on the full codebase.* Forces `prek` to evaluate every single file in the repository, regardless of git status. **Use this before opening a Pull Request.**
-* **`make check-from-ref`** *Runs checks on your entire branch history.* Automatically identifies all files changed since you branched off of the `main` branch and runs linting rules against them.
+* **`make check-from-ref`** *Runs checks on your entire branch history.* Automatically identifies all files changed since you branched off of the `master` branch and runs linting rules against them.
 * **`make check-last`** *Runs checks on your last commit.* If you just committed code and want to double-check that everything passes post-commit.
 * **`make update-deps`** *Keeps linter hooks up to date.* Upgrades `prek` hooks to their latest respective upstream versions and updates your local locked dependencies.
 
+### Running prek Standalone (Without Makefile)
+
+For developers on execution environments where running a `Makefile` is unavailable, restrictive, or unoptimized (such as native Windows environments without an active bash/make emulation layer), you can execute code quality workflows by interacting with `prek` directly using `uv`.
+
+#### 1. Bootstrap the Environment
+
+Before invoking `prek` manually, force `uv` to resolve and install the mandatory development groups and local hook ecosystems:
+
+```bash
+uv sync --all-groups
+```
+
+#### 2. Executing Standalone Hooks
+
+Once dependencies are synced inside your virtual environment, execute `prek` tasks via `uv run`:
+
+* **Check Staged Files Only:**
+
+```bash
+uv run prek run
+```
+
+* **Check the Entire Codebase:**
+
+```bash
+uv run prek run --all-files
+```
+
+* **Run Specific Linters Standalone:**
+  If you only wish to validate explicit targets (such as Python formatting, markdown linter rules, or security auditing profiles), pass the specific hook ID directly:
+
+```bash
+uv run prek run <hook_id> --all-files
+```
+
+#### 3. Updating Hooks Manually
+
+To keep linter definitions synchronized with upstream styling configurations without a `Makefile` shortcut, trigger an explicit update through the core engine:
+
+```bash
+uv run prek auto-update --freeze
+```
+
 ---
 
 ### Advanced Usage & Examples