Checks that every code fence carrying a guide=FILE#REGION pointer shows exactly that region of a file in the juneau-examples/juneau-examples-guides module of the Juneau checkout, and that every non-shell fence on a guide page carries a pointer. The module‘s own build compiles and tests those files, so a guide’s code cannot drift from code that works.
pages/guides/, or a file in juneau-examples-guides that a guide points at.build-docs.py runs it in its Links stage, and the docs gate runs it too.check-java-fences.py; for HTML anchors inside fences, check-code-fences.py.python3 scripts/check-guide-snippets.py --juneau-root ~/git/apache/juneau python3 scripts/check-guide-snippets.py --juneau-root ~/git/apache/juneau --docs-root /path/to/juneau-docs
| Option | Argument | Default | Meaning |
|---|---|---|---|
--juneau-root | directory | $JUNEAU_ROOT, then ../master, then ../juneau | The Juneau checkout holding juneau-examples/juneau-examples-guides. |
--docs-root | directory | parent of the scripts/ folder | The docs checkout whose pages/ tree (plus the *.mdx pages in src/pages/about/) is scanned. |
pages/**/*.md and src/pages/about/*.mdx (code_fences.iter_fences) and splits its info string on whitespace. A word guide=FILE#REGION is a pointer; at most one per fence. Other words (fragment, title="...", {1,3}, showLineNumbers) are ignored.FILE under the module's src/test/java and src/test/resources. A bare basename (PetResource.java) must match exactly one file; a relative path (SpringBootRestApi/pom.xml) is tried under each root. Sample POMs and config files live in src/test/resources/<GuideSlug>/ and are always named by relative path.region NAME and endregion NAME, written as a //, # or <!-- --> comment. A region may start above the package line. Region names are unique in a file and regions do not nest; every closer names its region.pages/guides/*.md except the 00.Guides.md landing), every fence whose language is not bash, sh, shell, console or text must carry a pointer. A text fence may carry one, so the “Run it” output can point at a resource file the guide's test asserts against.It never runs Maven: the module's tests are what make a region trustworthy.
One page:line: message line per problem (the line of the opening fence), with the first lines of a unified diff for a mismatch, then Guide fences checked: N; failing: M; regions unreferenced: K. Unreferenced regions are informational.
| Code | Meaning |
|---|---|
| 0 | Every pointer matches and no guide-page fence lacks one, including when no page carries a pointer. |
| 1 | Any problem: guide source not found, ambiguous guide source, region not found, region unterminated, endregion mismatch, duplicate region, nested region, guide fence does not match, more than one guide= pointer, malformed guide= pointer, guide fence without pointer, or guide module not found when a pointer exists but the module does not. An explicit --juneau-root that is not a Juneau checkout also exits 1. |
region NAME or endregion NAME with nothing else on it, so an INI or YAML comment that reads # region east opens a region.guide= word, so it never shows on the page.--juneau-root, the check passes only while no fence carries a pointer.check-java-fences.py, check-code-fences.py, code_fences.py, juneau_root.py, build-docs.pypages/developer-info/02.09.AiKnowledgeAuthoring.md (“Guide fences”)