Repository navigation
camel-docling: document that html_split_page cannot be used - #29720
Conversation
gnodet-bot
left a comment
There was a problem hiding this comment.
The description update correctly documents the broken value, but html_split_page is still listed in enums — the catalog will still advertise it as a valid option alongside the warning. Users who rely on IDE autocomplete or the catalog UI will see it as a valid choice and have to read the full description to discover it doesn't work.
Consider removing html_split_page from the enums list (or annotating it with @Deprecated if the enum type supports it), so the catalog stops presenting it as a valid option. The enums attribute drives autocomplete and validation; leaving a broken value there is at best confusing and at worst silently corrupts routes that use it on the CLI path (mapToDoclingFormat has no case for html_split_page and silently falls back to md).
If removing it would break backward compatibility for users who have outputFormat=html_split_page in their configs, an explicit validation on startup (throw IllegalArgumentException) would be better than silent fallback to markdown — users would at least know their config is wrong.
One further note: this PR is explicitly marked as a follow-up to #29594, which is not yet merged. Without #29594, the useDoclingServe=true rejection behavior referenced in the description doesn't exist on main yet, so this description would be ahead of the actual behavior. The merge order dependency is noted in the PR body, but it's worth confirming before merging.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
oscerd
left a comment
There was a problem hiding this comment.
Good follow-up to #29594, and the description text itself is accurate: html_split_page is rejected under useDoclingServe=true and the CLI operations each pass their own format, so documenting "use html instead" on outputFormat is the right move.
One thing to fix before this can go green: the regeneration is incomplete. The edit to @Metadata(description = ...) on outputFormat is in DoclingConfiguration.java and in the component's own META-INF/.../docling.json, but the two generated mirrors that the same description feeds were not regenerated:
catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/components/docling.jsonstill carries the old"Output format for document conversion".DoclingEndpointBuilderFactory(and the docling component builder factory) still have the old Javadoc for the option.
This is coming from a fork, so CI has not run yet, but when it does the uncommitted-changes check will fail on exactly those files. Regenerating and committing brings all four copies into step: building the module regenerates its own JSON, and the camel-catalog copy and the endpoint-dsl factory are regenerated from the same metadata. The source edit and the wording are fine, it is only the generated mirrors that need to catch up.
Claude Code on behalf of oscerd
davsclaus
left a comment
There was a problem hiding this comment.
Thanks @WMK666666, good to see the follow-up so quickly, and the text matches the error that #29594 throws. This should go in after #29594.
A few things:
- Regeneration (CI blocker, as oscerd noted): only the component's own
docling.jsonwas updated. The old description is still in the camel-catalog copy (catalog/camel-catalog/.../components/docling.json), inDoclingComponentBuilderFactory.javaand inDoclingEndpointBuilderFactory.java. ThedeprecationNotenoise you saw usually means the localcamel-package-maven-pluginis older than main; rebuilding tooling first (ormvn install -Dquickly) and then regenerating the module should give a clean diff. - Wording: on main
outputFormatis only read bySUBMIT_ASYNC_CONVERSION(DoclingProducer.java:379-381); every other operation uses its own format, on docling-serve as well as the CLI. Maybe: "Output format of the SUBMIT_ASYNC_CONVERSION operation; the other operations always use their own format. The html_split_page value is rejected, as docling-serve does not return the split pages; use html instead." - While on this annotation (
DoclingConfiguration.java:55-56):defaultValueismarkdown, butenumsonly hasmd, so catalog validation would flag the default as an invalid value. Could you addmarkdowntoenumsin this PR?
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
|
🌟 Thank you for your contribution to the Apache Camel project! 🌟 🐫 Apache Camel Committers, please review the following items:
|
The outputFormat option is only read by SUBMIT_ASYNC_CONVERSION; every other operation passes its own format. Say that in the description, and that html_split_page is rejected because docling-serve does not return the split pages, so the catalog stops advertising a value that always fails. Add markdown to the enums, which only listed md even though it is the default. Regenerate the four copies of the description: the component metadata, the camel-catalog copy, and both DSL builder factories.
96db3c9 to
99c687f
Compare
|
All three points are in 1. Regeneration (the CI blocker). The description now carries through all four copies,
No 2. Wording. Used yours verbatim:
I checked the premise first: 3.
|
gnodet-bot
left a comment
There was a problem hiding this comment.
Following up on my earlier review — all three issues have been addressed in 99c687f.
Regeneration ✅ — all five files are now in sync: DoclingConfiguration.java, both docling.json copies (component and catalog), DoclingComponentBuilderFactory.java, and DoclingEndpointBuilderFactory.java. The description propagates consistently across all four generated copies.
Wording ✅ — the description now matches the code exactly: outputFormat is only read by SUBMIT_ASYNC_CONVERSION (DoclingProducer.java:379-381), and html_split_page rejection is documented clearly.
markdown in enums ✅ — added. The author's note about enums not flowing to the generated JSON for String-typed options is accurate — the JSON does not advertise an enum list for outputFormat, so the catalog/validation concern is moot in practice.
The description now correctly scopes the option and warns about the broken value. LGTM.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
davsclaus
left a comment
There was a problem hiding this comment.
Thanks @WMK666666, all three points from my last review are in 99c687f:
- Regeneration: the new text is in the component JSON, the camel-catalog copy and both DSL builder factories.
- Wording: it now says the option is only read by
SUBMIT_ASYNC_CONVERSION, which matchesDoclingProducer(that operation also requiresuseDoclingServe=true, so "rejected" holds once #29594 is in). markdownis added toenums.
As noted before, this has to merge after #29594: the rejection the text describes only exists with that PR.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
✅ Generated files are up to dateAn earlier CI run reported uncommitted generated changes; the latest run no longer does. |
gnodet-bot
left a comment
There was a problem hiding this comment.
Previous findings are all addressed. The Regen commit (dabe31043b) corrects a trailing-period inconsistency between the @Metadata annotation (no period) and the generated JSON files (had a period). All five files are consistent. LGTM.
This review was generated by an AI agent, Hermès on behalf of @gnodet.
davsclaus
left a comment
There was a problem hiding this comment.
Re-approving on the new head: the Regen commit only drops the trailing period from the description in the two generated docling.json copies, so they match what the generator produces from the annotation. The rest is unchanged from my last review. Approved the CI runs; as before, this merges after #29594.
Claude Code on behalf of davsclaus. This review was generated by an AI agent and may contain inaccuracies; please verify all suggestions before applying.
|
🧪 CI tested the following changed modules:
🔬 Scalpel shadow comparison — Scalpel: 10 of 722 tested, 24 compile-only — current: 10 all testedMaveniverse Scalpel detected 10 affected modules (current approach: 10). Skip-tests mode would test 10 modules (4 direct + 9 downstream), skip tests for 24 (generated code, meta-modules) Modules Scalpel would test (10)
Modules with tests skipped (24)
All tested modules (37 modules, 5m 13s total)Total reactor time: 5m 13s
Top 20 slowest modules:
|
Follow-up to #29594, as suggested in its review:
outputFormatstill listshtml_split_pagein itsenums, and that value cannot produce anything.useDoclingServe=true, camel-docling: return DocTags content and reject html_split_page on docling-serve #29594 makes the request fail, becauseDocumentResponsehas no field for the split pages.DoclingProducer.java:309-353,:717).So the option description now says so, and the component metadata is regenerated.
Merge order: this only documents the behaviour that #29594 introduces, so it should go in after #29594. On its own the description would be a step ahead of
main.On the regenerated file:
docling.jsongains exactly the same sentence in both places the option is described (componentPropertiesandproperties), nothing else. I ran the generator and then kept only the two strings this change touches — the4.24.0-SNAPSHOTplugin I have locally also re-adds an emptydeprecationNoteto every property, whichmain's committed file does not carry, so a full regeneration from my side would have added ~143 lines of generator-version noise to this PR.formatter:validateandimpsort:checkpass, and the module compiles.