Doc Maintainers#56
Merged
Merged
Conversation
Split the monolithic maintainers/annotations.md reference into a section landing page plus one leaf page per annotation. The landing page keeps the shared intro (how annotations attach, argument shapes, the keyword compatibility matrix); each of the 17 leaf pages carries the EBNF-like syntax, its supported keywords, and at least one worked example, with deprecated/legacy forms named (no dedicated example) where a legacy syntax is still accepted — swagger:alias, swagger:type array, swagger:name vs the name: keyword, and the + name: chunk sigil vs the - name: YAML alias. Sort the at-a-glance annotation index alphabetically and repoint its Reference column, plus 28 cross-references across keywords, options, grammar, the shaping-the-output how-tos and the tutorials, at the new per-annotation leaf pages. Pure documentation move; no scanner or golden changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
…mples
Give every per-annotation page a consistent shape: a friendly Usage
quick-form at the top, a one-sentence lead in 'What it does', a formal
'Grammar (EBNF)' production, the supported keywords, and a worked Example.
Where a test-covered witness exists, the Example is now a live
{{< example >}} pane rendering the real annotated source beside the spec
the scanner actually produces (concepts/models, concepts/routes,
concepts/maps, concepts/meta) — so the reference can never drift from
real output. swagger:ignore and swagger:default, which produce no
definition, show source-only {{< code >}}; swagger:alias stays inert.
Add two witness regions to back the new panes and regenerate their
goldens:
- concepts/models: Color{ R,G,B,A uint8 } — one property per name
- concepts/maps: Settings — additionalProperties: {integer}
Tidy docs/examples/go.mod (testify 2.5.1->2.6.0, x/tools 0.46->0.47) to
match the root module so the examples module builds; this latent drift
was surfaced by the new witness tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Split the monolithic maintainers/keywords.md (~3800 words, three stacked
intro sections + one giant flat table) into a lean section landing plus one
page per keyword class.
The landing foregrounds the three things that matter about a keyword: its
class (a navigation table linking the subsection pages), the annotation
contexts that accept it (a transposed context matrix — the flip of the
annotation × keyword compatibility table), and its value shape. The
value-shapes and annotation-contexts reference tables move to a dedicated
appendix page that reads last.
Five class pages — parameters & responses, schema validations & decorators,
routes & operations, security, spec metadata — each carry a scoped summary
table and witness-backed {{< example >}} worked examples drawn from the
existing concepts/* fixtures. Each keyword has a single canonical home;
pages where it merely visits list it in their summary table and cross-link.
Repoint the 20 inbound keywords#anchor references across the annotation
pages and tutorials at the owning subsection page (absolute paths where a
basename collides with a tutorial of the same name).
Pure documentation move; no scanner or golden changes.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Add an opt-in 'railroad' shortcode that renders an ISO-14977 EBNF production as a Mermaid railroad diagram beside the plain EBNF text it complements (the text stays the authoritative grammar). Mermaid 11.16's railroad support is beta and its renderer collides when multiple diagrams are batched, so each is rendered in isolation via mermaid.render() with a unique id, sequentially. The script self-gates (loads Mermaid only on pages that contain a diagram), auto-quotes UPPERCASE lexer terminals so they get literal styling, and tracks the site's light/dark variant (re-rendering on Relearn's themeVariantLoaded). Mermaid is served as a local static asset so the rendered site makes no runtime CDN calls. Mermaid 11.16.0 is NOT committed — like the Relearn theme it is fetched per-environment (the CI 'Initialize theme and assets' step in update-doc.yml; locally per the doc-site README) and gitignored. Render diagrams for each parser family — top-level dispatch, schema body (validation + decorators expanded to the keyword level), operation (route / inline-operation / args), meta, and the classifier choice — using multi-rule blocks so block titles and their keyword detail both show. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
swagger:title and swagger:description are simple but first-class schema- family override annotations (AnnTitle / AnnDescription), yet the reference omitted them. Add them so the annotation vocabulary is complete: - grammar.md: ANN_TITLE / ANN_DESCRIPTION terminals, the two SchemaAnnotation productions, and a note on the override semantics (schema-parser dispatch, the | literal body, CodeEmptyOverride, context rejection on params/headers). - new per-annotation leaf pages swagger-title.md (weight 165) and swagger-description.md (weight 45), each with a live witness-backed example (shaping/overrides for the plain override, shaping/markdowndesc for the | literal block). - the section landing (now nineteen annotations; both added to the compatibility matrix) and the at-a-glance annotation index. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #56 +/- ##
=======================================
Coverage 81.55% 81.55%
=======================================
Files 84 84
Lines 8522 8522
=======================================
Hits 6950 6950
Misses 1149 1149
Partials 423 423 ☔ View full report in Codecov by Harness. |
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.
Change type
Please select: 🆕 New feature or enhancement|🔧 Bug fix'|📃 Documentation update
Short description
Fixes
Full description
Checklist