Skip to content

[DOCS] Update how to build docs; Clean up code quality section #2997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jiayuasu merged 1 commit into from
May 28, 2026
+43 −54
Merged

[DOCS] Update how to build docs; Clean up code quality section #2997

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 43 additions & 54 deletions docs/setup/compile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,103 +153,90 @@ uv sync --group docs
After installing MkDocs and MkDocs-Material, run these commands in the Sedona root folder:

```
uv run mkdocs build
cd docs-overrides && npm ci && npx gulp build
cd ..
uv run mike deploy --update-aliases latest-snapshot -b website -p
uv run mike serve
uv run mike serve -b website
```

## Code Quality Checks with `prek`, `uv`, and `make`

This guide explains how Apache Sedona manages code quality checks, formatting, and linting locally. 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 `Makefile`.
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`.

---

### Prerequisites

Before running any checks, ensure you have `uv` installed on your machine. If you don't have it yet, you can install it via:
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:

`curl -LsSf https://astral.sh/uv/install.sh | sh`
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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`.
> 💡 **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`.

---

### The Core Workflow: `uv` + `prek`

Our codebase uses `prek` to orchestrate linting and formatting workflows (such as Black, markdownlint, or oxipng).
Our codebase uses `prek` to orchestrate linting and formatting workflows (such as *Black*, *markdownlint*, or *oxipng*).

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.

---

### Available Make Commands

For maximum convenience, you should interact with `prek` entirely through the following `make` shortcuts.

#### 1. Run Checks on Staged Changes (Recommended before committing)

This runs `prek` only against the files you have explicitly staged using `git add`. It is incredibly fast.

`make check-stage`

#### 2. Run Checks on the Full Codebase

This forces `prek` to evaluate every single file in the repository, regardless of git status. Use this before opening a Pull Request.

`make check`

#### 3. Run Checks on Your Entire Branch History

This automatically identifies all files changed since you branched off of the `main` branch and runs linting rules against them.

`make check-from-ref`

#### 4. Run Checks on Your Last Commit

If you just committed code and want to double-check that everything passes post-commit:

`make check-last`

#### 5. Keeping Linter Hooks Up to Date
For maximum convenience, you should interact with `prek` entirely through the following `make` shortcuts:

To upgrade `prek` hooks to their latest respective upstream versions and update your local locked dependencies:

`make update-deps`
* **`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-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.

---

### Advanced Usage & Examples

#### Skipping Specific Hooks Locally

Sometimes a specific linter rule or hook blocks your workflow, or you want to isolate your testing to a single hook. You can bypass specific hooks by passing the `SKIP` environment variable directly to `prek`.
Sometimes a specific linter rule blocks your workflow, or you want to isolate your testing to a single hook. You can bypass specific hooks by passing the `SKIP` environment variable directly to `prek`.

* **Example:** Run all checks except the linter named `codespell`

```bash
SKIP=codespell make check-stage
```

* **Example:** Skip multiple hooks simultaneously (comma-separated)

* Example: Run all checks except the linter named codespell
`SKIP=codespell make check-stage`
* Example: Skip multiple hooks simultaneously (comma-separated)
`SKIP=codespell,gitleaks make check`
```bash
SKIP=codespell,gitleaks make check
```

#### Bypassing Automated Git Hooks (`--no-verify`)

If you have configured `prek` to run automatically as a native Git `pre-commit` hook on your system, it will block `git commit` if any files fail the quality gates.

If you need to commit a work-in-progress (WIP) branch quickly without fixing style errors, you can bypass the `prek` gate entirely using Git's built-in `--no-verify` (or `-n`) flag.

* Example: Force a commit despite failing linter checks
`git add .`
`git commit -m "WIP: basic structure for new feature" --no-verify`
```bash
git add .
git commit -m "WIP: basic structure for new feature" --no-verify
```

Warning: Continuous Integration (CI) runners will still execute all `prek` gates on your Pull Request. Bypassing hooks with `--no-verify` should only be used for temporary local savepoints.
> ⚠️ **Warning:** Continuous Integration (CI) runners will still execute all `prek` gates on your Pull Request. Bypassing hooks with `--no-verify` should only be used for temporary local savepoints.

---

### Housekeeping & Resetting Cache (`make clean`)

If your Python environment behaves unexpectedly, or if the linters fail to pick up recent changes due to aggressive local caching, you should reset your workspace back to a pristine state.
If your Python environment behaves unexpectedly, or if the linters fail to pick up recent changes due to aggressive local caching, you should reset your workspace back to a pristine state using:

Run the following command:

`make clean`
```bash
make clean
```

#### What happens under the hood?

Expand All @@ -267,8 +254,10 @@ Following a `make clean`, running any subsequent `make check` command will compl

When you execute a command like `make check`, the automation engine follows these exact steps:

1. `check-install`: Verifies `uv` is installed on your local path.
2. `install`: Triggers `uv sync --all-groups`, which automatically creates/syncs a `.venv` folder containing `prek` and all development dependencies.
3. `Execution`: Runs the target `prek` command within that guaranteed environment context.
1. **`check-install`**: Verifies `uv` is installed on your local path.
2. **`install`**: Triggers `uv sync --all-groups`, which automatically creates/syncs a `.venv` folder containing `prek` and all development dependencies.
3. **`Execution`**: Runs the target `prek` command within that guaranteed environment context.

`[ Your CLI ] ---> [ make check ] ---> [ uv syncs environment ] ---> [ prek executes hooks ]`
```
[ Your CLI ] ──> [ make check ] ──> [ uv syncs environment ] ──> [ prek executes hooks ]
```
Loading