docs: one page for a coding assistant, and a copy-page control on every page - #16
Merged
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three parts, all documentation.
A "Copy page" control above every page. A split button that copies the page's
Markdown, or opens it in ChatGPT / Claude / Perplexity. It works because
scripts/emit_markdown.pyruns after the site build and writes everydocs/<path>.mdnext to the HTML it built, so each page has a plain-text twin one URL away —
/guide/health/and/guide/health.md. The API reference declines the control withcopy_page: falsein its front matter: its Markdown is one instruction to a docstringrenderer, not the API, so a twin there would mislead rather than help.
docs/agents.md— the whole kit on one page, written for a coding assistant. Thepublic surface with real signatures and defaults, and the section that actually earns
its keep: the ordering rules a caller has to get right and gets no error for breaking.
Configure before
build(), because interceptors go togrpc.aio.server()atconstruction and there is no adding one later. The interceptor list is outermost first,
which is why
AsyncSentryInterceptormust sit after the exception handler — put itfirst and it captures nothing, ever, silently.
grace_period=Noneaborts in-flight RPCsimmediately rather than waiting forever.
context.abort()raisesgrpc.aio.AbortError,which
except grpc.RpcErrordoes not catch. AGrpcAppis single-use. Then themistakes a model makes with this API as WRONG/RIGHT pairs, the errors (all builtins —
the kit defines no exception classes, and a model will happily invent one), and a map
of which page to fetch for the rest.
The rule that keeps it true.
CONTRIBUTING.mdand the pull request checklist nowsay the page is part of the public API and goes stale in the same pull request that
changes it. A stale agents page is worse than none: it teaches a model an API that no
longer exists.
To see it: the Docs workflow builds and deploys on merge, and now runs the emit step
after
zensical build. Locally,make docs-build && uv run python scripts/emit_markdown.py—
zensical serverebuilds into the same directory without knowing about the twins, soa served preview answers 404 to the control.
Checks:
zensical build --cleanreports no issues,emit_markdown.pywrites 9 pageswith 1 declined,
make checkandmake test-unit(400 passed) are green, anduv.lockis untouched.
The four installed files (
docs/assets/stylesheets/copy-page.css,docs/assets/javascripts/copy-page.js,overrides/main.html,scripts/emit_markdown.py) are byte-identical across the organisation on purpose, sothey can be updated everywhere in one sweep.