davsclaus opened a new pull request, #26391: URL: https://github.com/apache/camel/pull/26391
Closes [CAMEL-24713](https://issues.apache.org/jira/browse/CAMEL-24713). Stacked on #26390 (the doc fixes it depends on); the base switches to `main` when that merges. ### What `eip-samples.json`, the fallback of `camel_catalog_sample` (CAMEL-24693), was hand-extracted from the docs. It is now generated by the build and the build fails when a documentation example does not validate. **A new goal `generate-doc-samples` in `camel-yaml-dsl-validator-maven-plugin`** — the plugin already depends on `camel-yaml-dsl-validator`, is built right after it and before `camel-jbang` in the reactor, so no reflection or classpath tricks are needed (`camel-package-maven-plugin` is built before the validator and cannot validate). It reads three sources: | Source | Which examples | Key | |---|---|---| | every page of `core/camel-core-engine/src/main/docs/modules/eips/pages` | all route examples | the page name: `split-eip` → `split`, `dead-letter-channel` → `deadLetterChannel` | | every page of `docs/user-manual/modules/ROOT/pages` minus `excludes` | all route examples are **validated**; only the pages in `pages` are sampled | configured: `routes=route`, `rest-dsl=rest`, `route-template=routeTemplate`, `route-configuration=routeConfiguration`, `exception-clause=onException`, `oncompletion=onCompletion`, `try-catch-finally=doTry` | | `entryPages` (`path=key`) | the examples starting with `- key:` | `yaml-dsl.adoc=beans` | A route example is a `[source,yaml]` block whose first line starts with `- ` (same rule as `EipDocExamplesTest` and `CatalogSamples.fromCatalog`); callouts (`# <1>`) are stripped. Any example that fails `YamlValidator` fails the build with the page, the message and the YAML. The output goes to `src/generated/resources/.../eip-samples.json`, same shape as before (`{key: [{source, yaml}]}`), sorted, written only when the content changed so CI's uncommitted-changes check catches drift. The hand file under `src/main/resources` is removed. Result: 103 names / 340 samples (the hand file had 103 / 325 — the difference is the examples fixed in #26390 plus the `beans` examples of `yaml-dsl.adoc`). The excludes are the user-manual pages that deliberately show YAML that is not a valid Camel file: `camel-*upgrade-guide*.adoc`, `camel-4-migration-guide.adoc`, `camel-jbang-transforming.adoc` (a transform input), `camel-report-maven-plugin.adoc` (an ellipsis), `improving-the-documentation.adoc` and `release-guide*.adoc` (Antora config). **`CatalogSamples.fromCatalog` also tries the bare page name.** It only looked for `<key>-eip`, so the 27 pattern pages without the suffix (`deadLetterChannel`, `intercept`, `keyValueRepository`, `messageHistory`, `transactionalClient`, …) were always served from the shipped file even though the catalog bundles them; now they follow the catalog of the Camel version in use like the other EIPs. The doc cache is keyed by name. **`yaml-dsl.adoc`:** the one hand-written sample (a bean declared in the file and called from a route) is now a documented example right after the first `beans` example, and the three script examples elided with `...` (a YAML document-end marker, so not valid YAML) now show a small real script. Catalog mirror regenerated. ### Tests - `GenerateDocSamplesMojoTest`: key derivation, example extraction (fragments and callouts), keying by EIP page / user-manual page / entry with excludes, and that an invalid example is reported as a failure. - `CatalogSamplesTest`: the generated file covers the EIPs and file entries (guards against the mojo producing a shrunken file, since the file is also the name index of `resolve()`), the pattern pages come from the catalog, the `beans` sample with a route is within the default limit. - `EipDocExamplesTest` is kept: it validates the same EIP pages from the catalog copy earlier in the reactor, with a clearer failure than a mojo. - Ran the mojo twice: second run reports the file unchanged. ### Not in this PR - `camel_catalog_sample` itself is not documented in the user manual (it was not in CAMEL-24693 either); the plugin page describes the goal and points to `camel-jbang-ai.adoc`. _Claude Code on behalf of davsclaus_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
