diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5451fe1..5073550 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,7 +15,7 @@ - [ ] Tests added or updated - [ ] `make check` passes locally (`ruff` + `mypy`) - [ ] `CHANGELOG.md` updated under `[Unreleased]` -- [ ] Documentation updated (if the public API changed) +- [ ] Documentation updated (if the public API changed), `docs/agents.md` included ## Related issues diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9b74f3..ac191ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,26 @@ Breaking changes: add `!` after the type (`feat!:`) or include a `BREAKING CHANG Update `CHANGELOG.md` under `[Unreleased]` for any user-visible change. +## The agents page + +`docs/agents.md` is the whole library on one page, written for a coding assistant: the +public API, the rules that break code when they are broken, the mistakes models make, and +a map of which page to fetch for the rest. People hand it to an assistant instead of the +site, which is what makes a stale one worse than none — it teaches a model an API that no +longer exists. + +It is part of the public API, so it changes in the same pull request the API does: a name +added, renamed or removed, a changed default or signature, a new rule a caller has to +obey. A new docs page means a new row in the documentation map. The review check is +mechanical — if the diff changes the public surface and `docs/agents.md` is untouched, the +pull request is not finished. + +The page carries its own weight only if it stays fetchable as text. Every page of the site +is written a second time as raw Markdown next to its HTML by `scripts/emit_markdown.py`, +which the Docs workflow runs after the build; the **Copy page** control above each page +reads those files. A page whose Markdown would not read as the page — the generated API +reference — declines both with `copy_page: false` in its front matter. + ## Integration tests Integration tests use [testcontainers](https://testcontainers.com/) to spin up a real diff --git a/docs/agents.md b/docs/agents.md index 9f1b8c9..ef384e1 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -230,7 +230,7 @@ Nesting is `child=`, up to five levels including the root. | Axis | Constructor | |---|---| -| Calendar over a timestamp | `TimeBoundaries(granularity=… \| calculator=…, tz="UTC", codec=None)` | +| Calendar over a timestamp | `TimeBoundaries(granularity=… | calculator=…, tz="UTC", codec=None)` | | Calendar over an encoded key | the same, with `codec=UUIDv7BoundaryCodec()` or `EpochBoundaryCodec(unit)` | | Fixed-width integer windows | `NumericBoundaries(step, origin=0, name_suffix="__{start}", cursor_source=…)` | | One value per partition | `IntegerSequence(start=1, name_suffix="__{value}", cursor_source=…)` | @@ -268,12 +268,12 @@ Every method takes the `TablePartitionConfig` as its first argument. | Method | Lock | DDL | Returns | |---|---|---|---| -| `inspect(config)` | no | no | `ActualTree \| None` | +| `inspect(config)` | no | no | `ActualTree | None` | | `plan(config, *, mode=PlanMode.MAINTAIN, now=None, windows=None)` | no | no | `MaintenancePlan` | | `apply(config, plan, *, continue_on_error=False, allow_config_drift=False)` | **yes** | yes | `MaintenanceResult` | | `maintain(config, *, skip_create=False, skip_detach=False, skip_drop=False, continue_on_error=False)` | **yes** | yes | `MaintenanceResult` | | `reconcile(config)` | no | yes | `MaintenanceResult` | -| `ensure_partition(config, period_or_window_or_position)` | no | yes | `PartitionInfo \| None` | +| `ensure_partition(config, period_or_window_or_position)` | no | yes | `PartitionInfo | None` | | `ensure_partitions(config, periods)` | no | yes | `list[PartitionInfo]` | | `partition_data(config, *, batch_rows=10_000, max_batches=None)` | **yes** | yes | `MigrationResult` | | `unpartition(config, into, *, batch_rows=10_000, max_batches=None, drop_emptied=False)` | **yes** | yes | `MigrationResult` | diff --git a/docs/assets/javascripts/copy-page.js b/docs/assets/javascripts/copy-page.js index c929b03..bc8a733 100644 --- a/docs/assets/javascripts/copy-page.js +++ b/docs/assets/javascripts/copy-page.js @@ -9,9 +9,10 @@ var RESET_AFTER_MS = 2000; - /* Where the Markdown of a page is written, as an absolute URL. The pair of - data attributes says how far the site root is from here and where this - page sits below it; scripts/emit_markdown.py writes the file to match. */ + /* Where the Markdown of a page is written, as an absolute URL. Two data + attributes say how far the site root is from here and where this page sits + below it; scripts/emit_markdown.py writes the file to match. The site's own + name is a third, so this file is the same in every project that carries it. */ function markdownUrl(widget) { var base = (widget.dataset.copyBase || ".").replace(/\/$/, ""); var page = widget.dataset.copyPage || ""; @@ -21,12 +22,15 @@ function prompt(widget) { var title = widget.dataset.copyTitle || document.title; + var site = widget.dataset.copySite || "project"; return ( "Read " + markdownUrl(widget) + ' -- the "' + title + - '" page of the pg-partsmith documentation -- so I can ask questions about it.' + '" page of the ' + + site + + " documentation -- so I can ask questions about it." ); } diff --git a/overrides/main.html b/overrides/main.html index 6ecf688..9d91b2d 100644 --- a/overrides/main.html +++ b/overrides/main.html @@ -11,7 +11,7 @@ with `copy_page: false` in its front matter. -#} {% if page.meta.copy_page != false %}
+ data-copy-title="{{ page.title }}" data-copy-site="{{ config.site_name }}">