docs: add zensical documentation site published to GitHub Pages

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DgcYQy7Mnh2afkmSg295uU

Author: Toilal

.github/workflows/mkdocs-develop.yml

@@ -0,0 +1,33 @@
+name: mkdocs-develop
+on:
+  push:
+    branches:
+      - develop
+# Per-target group: coalesce rapid develop pushes to the latest build, without
+# cancelling the main/preview deploys. Concurrent pushes to disjoint gh-pages
+# folders are handled by the deploy action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-develop
+  cancel-in-progress: true
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      - name: Deploy develop preview 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          # Publish the develop build under /dev/ without touching the stable site at the root.
+          target-folder: dev
+          clean: true

.github/workflows/mkdocs-preview.yml

@@ -0,0 +1,71 @@
+name: mkdocs-preview
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+# Per-PR group: a new push (or the close/cleanup) supersedes an in-flight build
+# for the same PR, without touching other PRs' or the main/develop deploys.
+# Concurrent pushes to disjoint gh-pages folders are handled by the deploy
+# action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-preview-${{ github.head_ref }}
+  cancel-in-progress: true
+permissions:
+  contents: write
+jobs:
+  deploy:
+    # Same-repo docs/* PRs only: fork PRs get a read-only token and cannot push to gh-pages.
+    if: >-
+      github.event.action != 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && startsWith(github.head_ref, 'docs/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Compute preview slug
+        id: slug
+        run: |
+          name="${GITHUB_HEAD_REF#docs/}"
+          name="$(printf '%s' "$name" | tr '/' '-' | tr -cd '[:alnum:]._-')"
+          echo "name=$name" >> "$GITHUB_OUTPUT"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      - name: Deploy MR preview 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          # Publish under preview/<branch-without-docs>/ without touching the rest of gh-pages.
+          target-folder: preview/${{ steps.slug.outputs.name }}
+          clean: true
+
+  cleanup:
+    # When a docs/* PR is merged or closed, remove its preview folder.
+    if: >-
+      github.event.action == 'closed'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && startsWith(github.head_ref, 'docs/')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: gh-pages
+      - name: Remove preview folder
+        run: |
+          name="${GITHUB_HEAD_REF#docs/}"
+          name="$(printf '%s' "$name" | tr '/' '-' | tr -cd '[:alnum:]._-')"
+          if [ -d "preview/$name" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git rm -r "preview/$name"
+            git commit -m "chore(docs): remove MR preview for ${name}"
+            git push
+          else
+            echo "No preview folder preview/${name} to remove."
+          fi

.github/workflows/mkdocs.yml

@@ -0,0 +1,36 @@
+name: mkdocs
+on:
+  push:
+    branches:
+      - main
+# Per-target group: a release deploy is never cancelled by the develop/preview
+# workflows. Concurrent pushes to disjoint gh-pages folders are handled by the
+# deploy action's fetch+rebase+retry.
+concurrency:
+  group: gh-pages-main
+  cancel-in-progress: false
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - run: uv run --only-group docs zensical build --strict
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: gh-pages
+          folder: site
+          clean: true
+          # Preserve the develop preview (dev/) and the docs/* MR previews (preview/)
+          # published by the mkdocs-develop and mkdocs-preview workflows.
+          clean-exclude: |
+            dev
+            preview

.gitignore

@@ -4,6 +4,9 @@ __pycache__/
 dist/
 build/
 
+# Zensical documentation build output
+/site
+
 # Python dist
 *.egg-info/
 .eggs/

README.md

@@ -26,6 +26,13 @@ Install
 $ pip install rebulk
 ```
 
+Documentation
+=============
+
+Full documentation is published on GitHub Pages:
+<https://toilal.github.io/rebulk>. A preview of the in-development `develop`
+branch is available at <https://toilal.github.io/rebulk/dev/>.
+
 Usage
 =====
 

docs/api.md

@@ -0,0 +1,92 @@
+# API reference
+
+This page lists the public symbols exported from the `rebulk` package (its `__all__`).
+
+```python
+from rebulk import (
+    Rebulk, Key, Rule, CustomRule,
+    AppendMatch, RemoveMatch, RenameMatch, AppendTags, RemoveTags,
+    ConflictSolver, PrivateRemover,
+    PRE_PROCESS, POST_PROCESS, REGEX_ENABLED,
+)
+```
+
+## Rebulk
+
+`class Rebulk(...)`
+
+Main entry point. A `Builder` that holds patterns, rules and nested Rebulk objects, and
+runs the matching pipeline. Key methods:
+
+- `string(*patterns, key=None, **options)` — add one or more string patterns.
+- `regex(*patterns, key=None, **options)` — add one or more regex patterns.
+- `functional(*patterns, key=None, **options)` — add one or more functional patterns.
+- `chain(**options) -> ChainBuilder` — start a chain of patterns (closed with `close()`).
+- `pattern(*patterns)` — add already-built `Pattern` objects.
+- `rules(*rules)` — register rules from a class, instance or module.
+- `rebulk(*rebulks)` — nest other `Rebulk` objects to compose their patterns and rules.
+- `defaults(**kwargs)` / `string_defaults` / `regex_defaults` / `functional_defaults` /
+  `chain_defaults` — set default options for subsequently built patterns.
+- `declare_keys(*keys)` — declare typed `Key` objects whose converters are inherited by
+  later patterns as per-name formatters.
+- `matches(string, context=None) -> Matches` — run the pipeline and return the results.
+- `check_keys(*, allowed_unused=()) -> list[str]` — declared key names no pattern can
+  produce (guards against typos / stale names).
+- `effective_patterns(context=None)`, `effective_rules(context=None)`,
+  `effective_keys(context=None)` — the patterns / rules / keys active for a given context.
+
+## Key
+
+`class Key(name, value_type, formatter=None)`
+
+A frozen, generic dataclass binding a match `name` to its `value_type` for type-safe
+retrieval. `formatter`, if given, is the `(str) -> T` converter applied to the matched
+substring; it defaults to `value_type` itself. Passing a key to a builder method (`key=`)
+wires up both the match name and the formatter, so `matches[key]` and `matches.all(key)`
+return precise types instead of `Any`. `value_type` must be scalar — a dataclass or
+`TypedDict` is rejected (assemble those with `Matches.to(...)`). The `converter` property
+returns the effective `(str) -> T` converter.
+
+## Rule / CustomRule
+
+`class Rule` — abstract base for a rule. Implement `when(matches, context)` (return truthy
+to trigger) and either `then(matches, when_response, context)` or a `consequence` class
+attribute. Class attributes `priority` (int, higher first) and `dependency` (another rule
+class) control ordering. `CustomRule` is the generic, typed rule base re-exported for
+building custom rules.
+
+## Consequences
+
+Consequence classes applied when a rule triggers (used as a rule's `consequence`):
+
+- `RemoveMatch` — remove the matched objects from the result.
+- `AppendMatch` — append new matches to the result.
+- `RenameMatch` — rename the matched objects.
+- `AppendTags` — add tags to the matched objects.
+- `RemoveTags` — remove tags from the matched objects.
+
+## Default processors
+
+- `ConflictSolver` — default `Rule` (priority `PRE_PROCESS`) that keeps the longer match
+  when matches overlap.
+- `PrivateRemover` — default `Rule` (priority `POST_PROCESS`) that removes matches flagged
+  as `private` from the final output.
+
+## Constants
+
+- `PRE_PROCESS` (`2048`) — priority for rules running before the standard rules.
+- `POST_PROCESS` (`-2048`) — priority for rules running after the standard rules.
+- `REGEX_ENABLED` — `True` when the optional [`regex`](https://pypi.python.org/pypi/regex)
+  backend is active (`REBULK_REGEX_ENABLED=1` and `regex` importable), otherwise `False`.
+
+## Other useful modules
+
+These are not in `__all__` but are part of the public surface:
+
+- `rebulk.match` — the `Match` and `Matches` classes and the `MatchesDict` mapping.
+- `rebulk.validators` — reusable validator functions (typically wired with
+  `functools.partial`), e.g. surrounding-character checks.
+- `rebulk.debug` — debug switches such as `CHECK_DECLARED_KEYS` (declared-key value-type
+  contract check, off by default).
+- `rebulk.introspector` — utilities to extract pattern / rule metadata from a configured
+  `Rebulk`.

docs/index.md

@@ -0,0 +1,84 @@
+# Rebulk
+
+Rebulk is a Python library that performs advanced searches in strings that would be
+hard to implement using the [`re` module](https://docs.python.org/3/library/re.html)
+or [string methods](https://docs.python.org/3/library/stdtypes.html#str) alone.
+
+It provides building blocks such as `Patterns`, `Match` and `Rule` that let you build
+a custom and complex string matcher through a readable, extendable, fluent API.
+
+The project is hosted on GitHub: <https://github.com/Toilal/rebulk>.
+
+## Features
+
+- **Composable patterns** — declare `string`, `regex` and `functional` patterns in bulk
+  on a single `Rebulk` object using a fluent, chainable API.
+- **Rich match model** — every result is a `Match` object with `value`, `start`, `end`,
+  `span`, `name`, `tags` and nested `children`; the `Matches` collection offers indexed
+  lookups by name, tag, position and proximity.
+- **Rule engine** — express conditional post-processing (filtering, renaming, tagging,
+  appending) as `Rule` classes with priorities and dependencies.
+- **Chains and repeaters** — compose ordered sequences of patterns with regex-like
+  quantifiers (`?`, `*`, `+`, `{n,m}`).
+- **Typed retrieval** — bind a match name to its value type with `Key` for type-safe
+  access, and project matches onto a dataclass or `TypedDict` with `Matches.to(...)`.
+- **Optional `regex` backend** — enable the [`regex`](https://pypi.python.org/pypi/regex)
+  module (repeated captures) at runtime with `REBULK_REGEX_ENABLED=1`.
+- **Fully typed** — the package ships a `py.typed` marker and passes `mypy --strict`.
+
+## Installation
+
+```sh
+pip install rebulk
+```
+
+To enable the optional [`regex`](https://pypi.python.org/pypi/regex) backend, install the
+`native` extra and set the environment variable at runtime:
+
+```sh
+pip install "rebulk[native]"
+export REBULK_REGEX_ENABLED=1
+```
+
+Rebulk requires Python 3.10 or later and has no runtime dependencies (the `regex`
+backend is optional).
+
+## Quickstart
+
+Regular expression, string and function based patterns are declared on a `Rebulk`
+object. It uses a fluent API to chain `string`, `regex` and `functional` methods to
+define the pattern types.
+
+```python
+>>> from rebulk import Rebulk
+>>> bulk = Rebulk().string('brown').regex(r'qu\w+').functional(lambda s: (20, 25))
+
+```
+
+Once the `Rebulk` object is fully configured, call `matches` with an input string to
+retrieve all `Match` objects found by the registered patterns.
+
+```python
+>>> bulk.matches("The quick brown fox jumps over the lazy dog")
+[<brown:(10, 15)>, <quick:(4, 9)>, <jumps:(20, 25)>]
+
+```
+
+If several `Match` objects are found at the same position, only the longer one is kept
+(this is the job of the default `ConflictSolver` rule).
+
+```python
+>>> bulk = Rebulk().string('lakers').string('la')
+>>> bulk.matches("the lakers are from la")
+[<lakers:(4, 10)>, <la:(20, 22)>]
+
+```
+
+## Where to go next
+
+- [Usage](usage.md) — build a `Rebulk`, declare the three pattern types, configure
+  pattern options, and read back `Match` / `Matches`.
+- [Rules & processors](rules.md) — write `Rule` classes and use the built-in
+  consequences and default processors.
+- [API reference](api.md) — the public symbols exported from the `rebulk` package.
+- [v5 design notes](v5-design.md) — background design notes.