docs(statements): restructure the Statements feature guide for the current model - #606
Draft
rsalesc wants to merge 23 commits into
Draft
docs(statements): restructure the Statements feature guide for the current model#606rsalesc wants to merge 23 commits into
rsalesc wants to merge 23 commits into
Conversation
Records the approved 5-page structure (Overview, Writing statements, Template context, Contest statements, Tutorials) for rewriting the Statements feature-guide docs to the current (v2) statement model. Scope is #570 (reference/feature-guide only); the #438 walkthrough stays a separate effort. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan to rewrite the five Statements pages to the current statement model, with canonical (non-stale) YAML/tex examples, a non-strict mkdocs-build + staleness-grep verification gate, and a commit per page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task 0 verification corrected several assumptions: --languages (no -l), no `editorial` block / no engine block-allowlist, contest PDFs keyed by statement name, `sample.explanation` is dead, render-specific namespaces. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…joins Rewrite docs/setters/statements/contest.md for the v2 model: the two contest-owned problem templates (standaloneProblemTemplate vs contestProblemTemplate), the (language, variant) join and its 0/>1 rule, building, documents (metadata-only), location/date, and the extends allowlist merge. Fold in the template-authoring guidance from the retired templates.md, delete that page, drop it from the nav, and repoint its inbound links (writing.md, context.md) at contest.md sections. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Unify template filenames on problem-standalone.rbx.tex / problem-in-contest.rbx.tex across the doc set; show the shared body file once; merge the two template subsections into a single "Custom blocks" that states the block -> problem.blocks.foo mechanic once with one guarded example; drop the duplicated bundled-default fallback note (kept canonical in the 0/1/>1 join bullets) so the Building warning covers only the unselected-dispatcher exception; make the tutorials note a clean cross-reference. Anchors #the-contest-owns-the-templates and #custom-blocks preserved, so inbound links from writing.md/context.md are untouched. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Repoint the profiling guide's inbound link to the surviving #building anchor on the statements overview, and anchor the context page's "Documents" link to contest.md#documents. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The memoryLimit field is documented in MB; the infosheet limits-table example mislabeled its column MiB. Align the label with the value. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…paths) Prefix the cheatsheet's in-statement var example with the required vars. namespace, document the actual registered Jinja filters in context.md and point the writing/contest "filters" links at it, standardize every statement source path on the plural statements/ directory, add assets to the cheatsheet extends inheritance list, and note positional variant selection (rbx st b <variant>) in the guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rsalesc
changed the title
…'s voice Restyle all five Statements pages (Overview, Writing, Template context, Contest, Tutorials) to match the maintainer's authentic docs voice — definition-first openings that motivate with a concrete "why", "let's"/ "you" register, opinionated guidance, short paragraphs, colon lead-ins + plain-language recaps around snippets, intent-matched admonitions, and point-onward sign-offs. Technical content (schema, examples, tables, headings, anchors, links, macros) is preserved unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the repeated "the nice part" tic (index/contest/tutorials), drop a redundant fallback note and padded emphasis in contest, fix a "which...which" stutter in context, and trim a throwaway quip in the overview. Prose-only; no technical content changed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Persist the reverse-engineered author style guide (from the maintainer's
own docs) at docs/plans/docs-writing-style-guide.md, wrapped in a raw
block so mkdocs shows the {{...}} macro examples literally. Point CLAUDE.md
at it so future doc work follows the same voice. Adds the "introduce a
concept before you use it / no forward-references" principle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…riting
Rework the overview's "three kinds" to define joining, documents, and
tutorials before the summary table instead of dropping the terms cold.
In the writing guide, stop forward-referencing template/config mechanics
the reader hasn't met yet: remove the premature params example, the
\VAR{problem.blocks.legend} rendering detail, the vars-vs-params aside,
and the problem.samples handle -- deferring each to the page that owns it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The note introduced the editorial/tutorial concept in the writing guide only to say a block doesn't exist. Tutorials own that topic; remove the aside rather than raise a concept the reader hasn't met. Co-Authored-By: Claude Opus 4.8 (1M context) <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
1 participant
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.
What
Restructures Feature Guide → Statements to the current statement model as five focused, example-driven pages (plus the design + plan that produced them).
Five pages (Feature Guide → Statements):
index.md) — the mental model:(language, variant)sources of sometype, thestatements/tutorials/documentskinds, a formats-at-a-glance table, the build commands, and the pipeline.writing.md, new) — rbxTeX-first authoring: blocks,\VAR{}/Jinja, samples & explanations, assets; short sections for Markdown/Jinja/LaTeX/PDF. Consolidates the oldformats/{rbxtex,latex,pdf}.mdpages.context.md, new) — theparams/vars/contest/problem/problemsnamespaces (render-specific, never merged), per-sample handles, and the LaTeX-Jinja filters (sci,rsci,escape,parent,stem).contest.md) — the contest-ownedstandaloneProblemTemplate/contestProblemTemplate, the(language, variant)join,documents/infosheets, the no-contest fallback, andextends. Absorbs the oldtemplates.md.tutorials.md, new) — editorials viarbx tut b/rbx contest tut b.Also: corrected the stale statements snippet +
-l→--languagesincheatsheet.md; repointed the{{rbxtex}}macro towriting; fixed dangling inbound links.Why
The hand-written statement guide pages documented the pre-v2 schema (
name/path/configure/match/joiner/override, statement-levelvars) — all removed in the current model. Closes the docs scope of #570 (reference/feature-guide). The #438 contest-statements walkthrough remains a separate effort.How it was built
Brainstormed the structure → design doc + task-by-task plan (
docs/plans/2026-07-29-statements-docs-restructure*.md), then executed subagent-driven with per-page spec + quality review and a final holistic cross-page pass. Every user-facing claim was verified against the code (schema.py,context.py,resolver.py,expander.py,latex_jinja.py, the CLI).Verification
uv run mkdocs build(non-strict) — no errors; only ~9 pre-existing unrelated warnings (autorefs dupes,docs/plans/*macro noise).sample.explanation/inputPath/outputPath), no-lflag.Status
Still a draft — the design doc + plan are included for review, and reviewers can walk the five pages. Ready to mark for review whenever you're happy with it.
🤖 Generated with Claude Code