Repository navigation
Read and search RESTest's documentation on the site, at the released version - #2
Merged
Merged
Conversation
…earchable, in the site's look Starlight builds /docs from RESTest's own Markdown at the version in restest-version. Before each build, scripts/sync-docs.mjs fetches that version, takes each page's title from its first heading, points every link at the site (or at GitHub at that version when it leaves the pages), copies the images the pages show, and reads the sidebar from docs/README.md and docs/manual/README.md. It fails, naming RESTest's file, on a page with no title, a link to nothing, two files at one address, an index of another shape, or a page in no index. Pagefind searches the pages, /llms.txt lists them for coding agents, and a workflow builds every pull request, publishes main on GitHub Pages, and builds from RESTest's master every week. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 tasks done
ssegura
added a commit
to isa-group/RESTest
that referenced
this pull request
Nov 6, 2026
…lease once it is published (#439) **Related:** isa-group/restest-site#2, which publishes the documentation as a website, now live at https://isa-group.github.io/restest-site/docs/. ## What you can do now that you could not before Read and search RESTest's documentation at one address, https://isa-group.github.io/restest-site/docs/, which the README and the skill for coding agents now give. Once this is merged and its key is set up, publishing a release moves the site on to that release by itself and checks that it did; and a pull request that would leave the site unable to build — a page in no index, an index of another shape, a page with no title, a link to a page's own title — fails here, naming the file, rather than after the release. ## Try it yourself With Java and git, from a clean clone: ```bash git clone --branch feat/m12-4-documentation-site https://github.com/isa-group/RESTest.git restest-docs-site cd restest-docs-site ./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \ -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Tests run:.*in io|BUILD' ``` ``` [INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.179 s -- in io.restest.arch.DocumentationSiteTest [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.044 s -- in io.restest.arch.DocumentedLinksTest [INFO] BUILD SUCCESS ``` Now add a page that no index lists, and a link to a page's own title, which the site shows above the page rather than as a heading: ```bash printf '# Faults, again\n\nThe same page twice.\n' > docs/faults-again.md printf '\nSee [the command line](command-line.md#the-command-line).\n' >> docs/faults.md ./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.Documentation*,io.restest.arch.DocumentedLinksTest' \ -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Expecting empty|BUILD' | sort -u ``` ``` Expecting empty but was: ["docs/README.md lists no entry for docs/faults-again.md, so the website's menu would not reach it; every page needs one, in it or in docs/manual/README.md"] Expecting empty but was: ["docs/faults.md links to command-line.md#the-command-line, and docs/command-line.md has no heading by that name"] [INFO] BUILD FAILURE ``` Undo it with `git checkout docs/faults.md && rm docs/faults-again.md`. With Node 26, the site builds from this branch, and its first group is named "Reference": ```bash git clone https://github.com/isa-group/restest-site ../restest-site && cd ../restest-site npm ci && npm run sync -- --from ../restest-docs-site && npx astro build | grep -E 'valid|built in' grep -o '"label": *"Reference"' src/generated/sidebar.json ``` ``` Copied 76 pages and 5 images of RESTest at master, from …/restest-docs-site · All internal links are valid. · [build] 77 page(s) built in 1.35s "label": "Reference" ``` The workflow cannot be tried before it is on `master` and its key is set up (see "Open questions"). ## How it works The site lives in its own repository, `isa-group/restest-site`. Before each build it takes RESTest at the release named in its one-line file `restest-version` and reads the Markdown under `docs/`, `README.md`, `AGENTS.md` and `CONTRIBUTING.md` as they are; its menu comes from the two indexes, the manual's numbered list of chapters and one group per `##` section of `docs/README.md`. Nothing of the site is in RESTest's build. ADR-0047 says why it is done this way, and everything in the pages the site relies on. When a release is published, the new workflow `documentation-site.yml` writes its tag into the site's `restest-version` with a deploy key, as `homebrew.yml` and `jbang.yml` write into the tap and the catalog: never over a higher version, and not again when it is there. That commit makes the site build from the new tag and publish it; the workflow then waits until the site's `llms.txt` names the version. A tag never changes, so a release whose pages the site cannot build would leave the site unable to publish anything until the site is changed. Two things keep that from happening: `DocumentationSiteTest` holds every pull request to the rules the site builds by, and before a tag the site is built by hand from `master` (a new step in the release steps of `docs/ci.md`). ## What changed in the code - `.github/workflows/documentation-site.yml` — three jobs: `version` checks the tag and that it is a published release; `push`, in the environment `restest-site`, writes the tag into the site with the key `RESTEST_SITE_KEY`, checking out nothing of RESTest while the key is loaded; `check-published` waits up to fifteen minutes for the site to name the version. Started by a release's publication, or by hand with a tag. No pull-request trigger: it would test a regular expression and nothing of the writing. - `restest-arch-tests/.../DocumentationSiteTest.java` — the site's rules as functions of a folder, applied to the repository and, with `@TempDir`, to a small documentation broken in 24 ways, each of which has to be reported. Two rules are stricter than the site: every chapter of `docs/manual/` is in the manual's list, and each item of that list starts with its link. - `DocumentedLinksTest.java` — its link pattern, line reader and code-fence filter are shared with the new test; and a page's title, its first `# ` heading, is no longer a heading a link may name, since the site shows the title above the page rather than as a heading. - `docs/adr/0047-the-documentation-site.md` — the decision, what the site depends on, what only the site checks, and the alternatives; `docs/adr/README.md` lists it, and ADR-0031, whose manual had one rendering, is amended. - `docs/ci.md` — five workflows; a section on the documentation site with its jobs and what to set up once; the release step before the tag; three runs to see green after publishing; the test in the table of gates. `docs/DESIGN.md`'s quality gates say the same in a line. - `docs/README.md` — the first section is now "Reference", the name of its group on the site. - `README.md`, `skills/restest/SKILL.md` and its copy in `docs/for-coding-agents.md` — the site's address, and, for agents, `llms.txt`. - `AGENTS.md` — a row of "Where things are" for the site. - `docs/schemas.md` — a line that began with `> plan.yaml`, which Markdown, GitHub's included, showed as a quote. ## Evidence - [x] Tests: one class added, `DocumentationSiteTest`, with three tests (the repository, a well-formed documentation, and 24 broken ones); `DocumentedLinksTest` refuses a link to a page's title. `./mvnw verify`: all green, 157 architecture and documentation tests. — the checks of this pull request - [x] Architecture tests: 157, none weakened; the rule on links is stricter. - [x] Mutation score: not applicable; no oracle or constraint touched. - [x] Per-request overhead: not applicable. - [x] Smoke run: not applicable; nothing a run does changes. - [x] Idle time: not applicable. - [x] Artefact: the site built from this branch with its own script (`npm run sync -- --from <this checkout> && npx astro build`): 76 pages, every internal link valid, the first group named "Reference". `actionlint` is clean on the workflow. Its comparison tried against the site's real `restest-version` (`v2.4.0`): `v2.5.0` and `v2.10.0` are written, `v2.4.0` is there already, `v2.3.0` is left, and a missing file is written. ## Decisions taken - **The site documents the latest release, and is moved on by a deploy key when one is published** (maintainer), as Homebrew's tap and the jbang catalog are. - **The site's address is `isa-group.github.io/restest-site` for now** (maintainer). When the project has a domain, the README, the skill, ADR-0047, `docs/ci.md` and the workflow change with it, and GitHub sends the old address on. - **`llms.txt` is named in the skill too** (maintainer), so an agent can read a page the skill does not cover; the skill says it describes the latest release, which may not be the version run. - **A release whose pages the site cannot build: the site is changed until it builds that tag**, and `restest-version` never goes back (maintainer). Hence the step before every tag: the site built by hand from `master` after the pull request that prepares the release, since its weekly build is older than that pull request. - **`restest-version` holds the tag with its `v`**, the only form the site reads; versions are compared without it, since `sort -V` would otherwise rank `v2.4.0` above `2.5.0` and leave the site behind with a green run. - **The workflow is `documentation-site.yml`**, not `site.yml`, the name of the site's own workflow, so that "the run of site.yml" is never ambiguous. - **A Java test that restates the site's rules**, rather than running the site's own build on RESTest's pull requests: that would be one set of rules, but Node in RESTest's CI and every pull request here depending on the site's `main`. ADR-0047 lists what only the site checks: links in raw HTML, reference-style links, links leaving the repository, headings the site names differently from GitHub, and two files at one address. - **ADR-0031 is amended**: its manual "has one rendering", which the site makes untrue. - Not taken from reviewers: a reusable workflow shared with `homebrew.yml` and `jbang.yml`, which would change both; a `version.json` on the site in place of the sentence of `llms.txt` the workflow waits for, which ADR-0047 records; reporting a missing index as a problem rather than the failure to read it, which names the file already. ## Open questions - **Before 2.5.0 is published, set up once** what `docs/ci.md` describes: the environment `restest-site` in this repository, limited to `master` and `v*`, created first; an SSH deploy key with write access on `isa-group/restest-site`; its private half as `RESTEST_SITE_KEY` in that environment. Then run the workflow by hand from `master` with `v2.4.0`: `push` should find the tag there already, and `check-published` should be green. - In the site, a small pull request follows: a comment beside `llms.txt`'s opening sentence saying this workflow waits for it, its README in the present tense, and Mermaid diagrams before 2.5.0, the first release with one. --- - [x] Targets `master` - [x] English throughout, including comments and test names - [x] The hard rules in `AGENTS.md` hold 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.
Related: #1, the look this builds on. A pull request in RESTest follows once the site is live (see "Open questions").
What you can do now that you could not before
Read and search RESTest's documentation as a website: the manual, every reference page and every decision record of the latest release, v2.4.0, with a menu built from RESTest's own indexes, search with no outside service, and the light and dark look of the site. Nothing in RESTest changed for it, and an
llms.txtpoints a coding agent at every page's Markdown in that version.Try it yourself
With Node 26 and git, from a clean checkout:
Real output, from a fresh clone of this branch (the build's list of pages left out):
In the browser: the manual's chapter 4 is at
/restest-site/docs/manual/reading-what-a-run-says/; search for "exit code"; switch between following the system, light and dark with the three buttons at the top right; narrow the window to a phone's width.http://localhost:4321/restest-site/llms.txtis the index for agents.To see the build refuse a page, break a link in a copy of RESTest and build from it:
A link to a heading that does not exist,
command-line.md#exit-code, gets past that step and fails the build instead:Undo it with
git -C ../RESTest checkout docs/faults.md.npm run sync -- --ref master && npx astro buildbuilds from what the next version will be.How it works
Before each build, a script takes RESTest at the version written in the one-line file
restest-version(v2.4.0). It never changes RESTest's files: it reads the Markdown indocs/and the three files at the root thatdocs/README.mdlinks, and writes each as a page of the site, with its first#heading as the title and every link pointed at the site. A link to another page goes to that page; to an image, to a copy of it; to any other file of RESTest, such asLICENSE, to GitHub at that version. Only the links change: the rest of each file stays byte for byte as RESTest has it.The menu on the left is read from RESTest's two indexes: the numbered list of chapters in
docs/manual/README.md, and one group per##section ofdocs/README.md, with that section's table giving the entries. A page that is in neither index, a link to nothing, a page with no title or an index of another shape stops the build, naming the file in RESTest, so that a change in RESTest cannot quietly leave a page out of the site.When RESTest publishes a version, a workflow of RESTest's, added in its follow-up pull request, will write the new version into
restest-versionhere. That commit, like any other onmain, rebuilds the site and publishes it on GitHub Pages. Once a week the site is also built from RESTest'smaster, without publishing it, so that a change there that would break the site is known before the next release.What changed in the code
scripts/sync-docs.mjs— the step that copies the documentation: takes RESTest at a version (--ref) or from a folder (--from), keeps the shallow clone in.restest/between runs, and writes the pages, the images, the menu andllms.txt. Git is called with arguments, never through a shell, and a version is accepted only if it is a plain git name.scripts/lib/— what that step does, one file per job:pages.mjs(which files are pages, their address, their title),links.mjs(where each link leads, includingsrc,srcsetandhrefin raw HTML),sidebar.mjs(the menu from the two indexes),llms.mjs(the index for agents),markdown.mjs(parsing, and changing only the characters of a link's address) andrefs.mjs(which version names are accepted).astro.config.mjs,site.config.mjs,src/content.config.ts— the site with Starlight, athttps://isa-group.github.io/restest-site/, with/leading to/docs/until the landing page exists.src/styles/docs.css— Starlight in the look of pull request The site's look: colours light and dark, three typefaces and RESTest's logo in SVG #1: its colours and type taken fromtokens.css, nothing under 14 px, the menu, titles and "On this page" as the mock-up drew them, and on a wide screen the menu, the text and "On this page" together in the middle of the window.src/components/ThemeSelect.astro— the theme in one click, with three buttons, in place of Starlight's drop-down; in the header on a phone too..github/workflows/site.yml— builds every pull request, publishesmainon GitHub Pages, and builds weekly frommasterwithout publishing. Actions are pinned by commit.restest-version,.nvmrc,public/favicon.svg,README.md— the version to publish, Node 26, the logo's check as the icon, and how to build and what the step reads and writes.test/— 47 tests withnode --test; those of the menu read RESTest's own two indexes at v2.4.0, copied as fixtures.Left for later: drawing Mermaid diagrams, before 2.5.0, the first version with one; the full header of the mock-up, with the landing page; breadcrumbs, if wanted.
Evidence
npm test), covering addresses, titles, links in Markdown and raw HTML, the menu from both indexes,llms.txtand the accepted version names, with each kind of malformed input the build refuses.master(75 pages and 5 images, 76 built), every internal link and heading valid. Measured in Chrome over seven pages, in both themes, at desktop width and at 375 px: no text under 14 px, search included, and the lowest contrast 6.53 : 1 in dark and 5.44 : 1 in light. No horizontal scrolling from 320 px to 2560 px. All 26 links ofllms.txtanswer 200.npm audit: 0 vulnerabilities;actionlint: clean.Decisions taken
master(maintainer), so it describes what users have installed. The five documentation pull requests merged since v2.4.0 appear with 2.5.0;npm run sync -- --ref mastershows them now.restest-versionwith a deploy key, when a release is published and only if the version is higher (maintainer), as it already does for Homebrew and jbang: no personal token to expire, no question to GitHub's API, and the same commit always gives the same pages. RESTest'srelease.ymlonly leaves a draft, so a trigger there would have rebuilt the previous version.##headings (maintainer). RESTest's follow-up pull request renames "Using RESTest" to "Reference"; until then the site says "Using RESTest"./docs/manual/a-first-run/), so that inserting a chapter does not move the others; decision records keep theirs, which is what cites them.github-slugger(ISC), the one GitHub and Astro use, so#exit-codesmeans the same on both.<img>is dropped from its README page: it is black on opaque white, a white box in the dark theme, and the header shows the logo already. The site finds it by its file name,RESTLogo_Black.png; RESTest's follow-up ADR records that.<picture>with a dark source becomes two images, each hidden in the other theme, so it follows the theme the reader picks rather than only the system's.--authinto–authand straight quotes into curly ones, which GitHub never does.pagination: false): the chapters of the manual already end by linking the next one, and between reference pages the order means nothing.i18ncollection and a404entry; both come from Starlight with a single language, and defining the collection to silence the first adds another.dependabot.yml: RESTest keeps automatic updates off, and Starlight is still 0.x.--sl-color-bg, kept so that the page's background does not depend on how Starlight derives it; and droppingcancel-in-progress: false, kept so that the workflow says a publication is never cut short.Open questions
master's documentation, as a "next" version beside the released one? It is not in this pull request.AGENTS.md, the workflow that writesrestest-version, the rename to "Reference", and a line ofdocs/schemas.mdthat starts with> plan.yamland so shows as a quote, on GitHub too.mainAGENTS.mdhold🤖 Generated with Claude Code