check-guide-snippets.py

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.

When to use

  • After editing a guide page under pages/guides/, or a file in juneau-examples-guides that a guide points at.
  • As part of a full build: build-docs.py runs it in its Links stage, and the docs gate runs it too.
  • For Java that does not parse, use check-java-fences.py; for HTML anchors inside fences, check-code-fences.py.

Usage

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

Options

OptionArgumentDefaultMeaning
--juneau-rootdirectory$JUNEAU_ROOT, then ../master, then ../juneauThe Juneau checkout holding juneau-examples/juneau-examples-guides.
--docs-rootdirectoryparent of the scripts/ folderThe docs checkout whose pages/ tree (plus the *.mdx pages in src/pages/about/) is scanned.

What it does

  1. Reads every fence in 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.
  2. Resolves 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.
  3. Finds the region between marker lines 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.
  4. Normalizes the fence body and the region body the same way: CRLF to LF, tabs expanded to four-column stops, trailing whitespace stripped, common indentation removed, leading and trailing blank lines dropped. They must be equal.
  5. On a guide page (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.

Output and exit codes

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.

CodeMeaning
0Every pointer matches and no guide-page fence lacks one, including when no page carries a pointer.
1Any 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.

Gotchas

  • Two test classes with the same basename in different packages make a basename pointer ambiguous; give each guide its own class names.
  • A marker line is any comment line region NAME or endregion NAME with nothing else on it, so an INI or YAML comment that reads # region east opens a region.
  • Docusaurus ignores the guide= word, so it never shows on the page.
  • With no checkout found and no --juneau-root, the check passes only while no fence carries a pointer.

See also

  • check-java-fences.py, check-code-fences.py, code_fences.py, juneau_root.py, build-docs.py
  • pages/developer-info/02.09.AiKnowledgeAuthoring.md (“Guide fences”)