From 5c4bcbfea869d05f5563dc5b1104259e03d84ed6 Mon Sep 17 00:00:00 2001 From: Alexey Shalaev <75322386+AlexeyShalaev@users.noreply.github.com> Date: Sun, 6 Sep 2026 18:56:24 +0300 Subject: [PATCH 1/2] docs: the agents page is part of the public API, and one shared copy-page script --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 20 ++++++++++++++++++++ docs/assets/javascripts/copy-page.js | 12 ++++++++---- overrides/main.html | 2 +- 4 files changed, 30 insertions(+), 6 deletions(-) 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/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 }}">