Bring the documentation and the website up to the unreleased changes - #50
Merged
Merged
Conversation
Five things the pages did not say since 0.10.0. The command-line host was invisible: no page and no README section named `accent-proust fmt` or `validate`, and the docs index routed "a CLI" to the Rust page. The site has a Command line page now, third in the navigation after Rust and JavaScript; the three pages after it are renumbered so the order reads that way, and their slugs are unchanged. The root README has a section, and the landing page's browser feature is a browser-and-shell one. The npm README and the JavaScript page did not record what the vocabulary extraction changed: that one schema file now serves both hosts, that a schema object is read key by key so a class instance works, that an `undefined` variable is `null`, that a `type` list may not nest, and that a property whose getter throws is refused rather than read as absent. The npm README ships with the next release, so this was on the release path. The architecture page's lead and description still said "one trait seam, two responsibilities left outside" above a body that said three traits; its workspace table listed one member of three. The root README's minimum Rust version said 1.82 where the CI job runs 1.96. The site builds with the new page, every /docs/* link on it resolves, and the README example still runs.
Eight findings from the review of #50, and three it cut for room. The one that matters most was a claim made in five places that the code contradicts: "a schema file written for one host is read by the other unchanged". The browser host reads an object, not a file. What is shared is the vocabulary; a schema declared for one host is accepted by the other, and a JSON file is the one spelling both read as it stands, the shell from disk and the browser through `JSON.parse`. Every page says that now. The Command line page omitted what the crate README knew: that `fmt` refuses a document still changing after four passes, with exit 2; that `parse` adds positions in the bindings' shape and a `file` label upstream does not write; that `--var x=` is `null`; and it never named or linked the vocabulary crate. The theme's hand-written footer had no entry for the page, and the site's `llms` description and the landing page's `description` did not name the command line. The changelog still said the command-line host "will" read through the vocabulary crate; it does. The README's minimum Rust version drifted once because nothing read it; `tests/readme.rs` pins the sentence to the manifest's `rust-version` now. The crate README leads with `cargo install --path`, which is what the outer pages say.
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.
Documentation only: no code, no manifests, no behaviour. Five things the pages did not say since 0.10.0, found by auditing every page against the
Unreleasedchangelog.What changed
/docs/cli), third in the navigation after Rust and JavaScript. The three pages after it are renumbered (04.language,05.architecture,06.divergences) so the order reads that way; slugs come from the name, so no link changes. The docs index gains a "Start here" row and no longer routes "a CLI" to the Rust page.undefinedvariable isnull; atypelist may not nest; a property whose getter throws is refused as unreadable rather than read as absent. The npm README ships with the next release.leadanddescriptionsaid "one trait seam, two responsibilities left outside" above a body that said three traits; both now match. Its workspace table lists all three members, and the paragraph after it says why a binary is a host and the vocabulary crate is not.Verified
scripts/build-site.shbuilds with the new page;/docs/rust,/docs/javascript,/docs/cli,/docs/language,/docs/architectureand/docs/divergencesall come out at their slugs; every/docs/*link across the built site resolves;cargo run --example readmestill runs; fmt and the library tests pass.Review fixes
Eight findings from
/code-reviewand three it cut for room, all taken:JSON.parsein the browser).fmtcannot settle, and the four-pass bound stated;parse's two additions over upstream (bindings-shape positions, afilelabel) restored; the--var x=→ null row; the vocabulary crate named and linked.site/config.yaml'sllmsdescription and the landing page'sdescriptionname the command line.tests/readme.rspins the README's MSRV sentence toCARGO_PKG_RUST_VERSION, so the drift that put 1.82 on the front page cannot recur silently.cargo install --path, as the outer pages do.Rebuilt the site: the footer on every page links
/docs/cli,llms.txtnames the command line, all six doc slugs present.