Skip to content

camel-docling: document that html_split_page cannot be used - #29720

Merged
davsclaus merged 2 commits into
apache:mainfrom
WMK666666:docling-outputformat-html-split-page
Nov 13, 2026
Merged

davsclaus merged 2 commits into
apache:mainfrom
WMK666666:docling-outputformat-html-split-page

Conversation

@WMK666666

Copy link
Copy Markdown
Contributor

Follow-up to #29594, as suggested in its review: outputFormat still lists html_split_page in its enums, and that value cannot produce anything.

So the option description now says so, and the component metadata is regenerated.

@Metadata(description = "Output format for document conversion. The html_split_page value is rejected
          when useDoclingServe is true, as docling-serve returns no split pages, and the CLI operations
          pass their own format; use html instead", ...)

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.json gains exactly the same sentence in both places the option is described (componentProperties and properties), nothing else. I ran the generator and then kept only the two strings this change touches — the 4.24.0-SNAPSHOT plugin I have locally also re-adds an empty deprecationNote to every property, which main'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:validate and impsort:check pass, and the module compiles.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 oscerd left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.json still 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 davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.json was updated. The old description is still in the camel-catalog copy (catalog/camel-catalog/.../components/docling.json), in DoclingComponentBuilderFactory.java and in DoclingEndpointBuilderFactory.java. The deprecationNote noise you saw usually means the local camel-package-maven-plugin is older than main; rebuilding tooling first (or mvn install -Dquickly) and then regenerating the module should give a clean diff.
  • Wording: on main outputFormat is only read by SUBMIT_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): defaultValue is markdown, but enums only has md, so catalog validation would flag the default as an invalid value. Could you add markdown to enums in 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.

@github-actions

Copy link
Copy Markdown
Contributor

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

  • First-time contributors require MANUAL approval for the GitHub Actions to run
  • You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
  • You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
  • Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

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.
@WMK666666
WMK666666 force-pushed the docling-outputformat-html-split-page branch from 96db3c9 to 99c687f Compare November 12, 2026 14:41
@WMK666666

Copy link
Copy Markdown
Contributor Author

All three points are in 99c687f:

1. Regeneration (the CI blocker). The description now carries through all four copies, +23/−10 over five files:

file change
DoclingConfiguration.java the annotation
components/.../docling.json the two entries that describe the option (componentProperties and properties)
catalog/camel-catalog/.../components/docling.json same file, it is a straight copy of the component's own JSON
DoclingComponentBuilderFactory.java one javadoc block
DoclingEndpointBuilderFactory.java the three javadoc blocks (consumer, producer, advanced)

No deprecationNote noise this time. On how the four generated copies were produced: I regenerated the component metadata and then applied the generator's own javadoc wrapping rule to the catalog copy and the DSL factories — 78 - indent as the line width, breaking at the last space, '.' appended only when the description lacks one (component-builder.vm:61, ComponentDslMojo.javadoc, EndpointDslMojo.createBaseDescription). Before trusting it I checked that this rule reproduces every existing option block in both files byte for byte: 60 of 61 in DoclingComponentBuilderFactory, 358 of 361 in DoclingEndpointBuilderFactory. The only misses are the file header paragraphs, which carry deliberate newlines. So the four DSL paragraphs are what a full build produces, not hand-typed.

2. Wording. Used yours verbatim:

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.

I checked the premise first: DoclingProducer.java:379-381 is the only place the option is read, and line 512 uses the format recorded on the task entry, so the description now matches the code.

3. markdown in enums. Added — enums = "markdown,md,json,html,html_split_page,text,doctags". One thing worth knowing: this is annotation-only, it changes no generated file, because the metadata generator does not emit enums for String options (ocrLanguage has a long enums list and no enum in the JSON either). So if the catalog validation you mentioned reads the JSON rather than the annotation, it still cannot see the list — tell me if you want that fixed properly in a separate issue.

formatter:validate, impsort:check and a compile of the module pass. CI still needs the approval for a first-time contributor.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 matches DoclingProducer (that operation also requires useDoclingServe=true, so "rejected" holds once #29594 is in).
  • markdown is added to enums.

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.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

✅ Generated files are up to date

An earlier CI run reported uncommitted generated changes; the latest run no longer does.

@gnodet-bot gnodet-bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 davsclaus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@github-actions

Copy link
Copy Markdown
Contributor

🧪 CI tested the following changed modules:

  • catalog/camel-catalog
  • components/camel-ai/camel-docling
  • dsl/camel-componentdsl
  • dsl/camel-endpointdsl

🔬 Scalpel shadow comparison — Scalpel: 10 of 722 tested, 24 compile-only — current: 10 all tested

Maveniverse 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)
  • camel-docling ← components/camel-ai/camel-docling/src/generated/resources/META-INF/org/apache/camel/component/docling/docling.json, components/camel-ai/camel-docling/src/main/java/org/apache/camel/component/docling/DoclingConfiguration.java
  • camel-jbang-mcp ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-mcp ← downstream of org.apache.camel:camel-jbang-core
  • camel-jbang-plugin-tui ← downstream of org.apache.camel:camel-catalog
  • camel-jbang-plugin-validate ← downstream of org.apache.camel:camel-yaml-dsl-validator
  • camel-jbang-run ← downstream of org.apache.camel:camel-catalog
  • camel-langchain4j-ingest ← downstream of org.apache.camel:camel-docling
  • camel-launcher-container ← downstream of org.apache.camel:camel-launcher
  • camel-yaml-dsl-validator ← downstream of org.apache.camel:camel-catalog
  • camel-yaml-dsl-validator-maven-plugin ← downstream of org.apache.camel:camel-yaml-dsl-validator
Modules with tests skipped (24)
  • apache-camel
  • camel-allcomponents
  • camel-catalog-console
  • camel-catalog-maven
  • camel-catalog-suggest
  • camel-endpointdsl-support
  • camel-itest
  • camel-jbang-core
  • camel-jbang-it
  • camel-jbang-main
  • camel-jbang-plugin-edit
  • camel-jbang-plugin-generate
  • camel-jbang-plugin-kubernetes
  • camel-jbang-plugin-test
  • camel-kamelet-main
  • camel-launcher
  • camel-report-maven-plugin
  • camel-route-parser
  • camel-yaml-dsl
  • camel-yaml-dsl-deserializers
  • camel-yaml-dsl-maven-plugin
  • coverage
  • docs
  • dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (37 modules, 5m 13s total)

Total reactor time: 5m 13s

Module Duration Status
Camel :: JBang :: MCP 43.2s SUCCESS
Camel :: AI :: LangChain4j :: Ingest 29.7s SUCCESS
Camel :: JBang :: Plugin :: Validate 24.7s SUCCESS
Camel :: YAML DSL :: Validator 23.5s SUCCESS
Camel :: YAML DSL 20.6s SUCCESS
Camel :: JBang :: Run 20.0s SUCCESS
Camel :: AI :: Docling 19.8s SUCCESS
Camel :: Catalog :: Camel Catalog 19.3s SUCCESS
Camel :: Component DSL 15.7s SUCCESS
Camel :: JBang :: Plugin :: Kubernetes 13.0s SUCCESS
Camel :: Docs 12.1s SUCCESS
Camel :: JBang :: Plugin :: Testing 10.6s SUCCESS
Camel :: Kamelet Main 9.6s SUCCESS
Camel :: Catalog :: Camel Report Maven Plugin 6.9s SUCCESS
Camel :: YAML DSL :: Validator Maven Plugin 6.0s SUCCESS
Camel :: Catalog :: Camel Route Parser 5.9s SUCCESS
Camel :: YAML DSL :: Deserializers 5.9s SUCCESS
Camel :: JBang :: Plugin :: Generate 4.3s SUCCESS
Camel :: All Components Sync point 4.0s SUCCESS
Camel :: Assembly 2.6s SUCCESS
Camel :: Catalog :: Maven 2.5s SUCCESS
Camel :: YAML DSL :: Maven Plugins 2.4s SUCCESS
Camel :: JBang :: Plugin :: MCP 1.7s SUCCESS
Camel :: Catalog :: Suggest (deprecated) 1.6s SUCCESS
Camel :: Coverage 1.4s SUCCESS
Camel :: JBang :: Integration tests 1.3s SUCCESS
Camel :: JBang :: Plugin :: Edit 0.9s SUCCESS
Camel :: Launcher :: Container 0.8s SUCCESS
Camel :: Catalog :: Dummy Component 0.8s SUCCESS
Camel :: JBang :: Main 0.8s SUCCESS
Camel :: Endpoint DSL :: Support 0.7s SUCCESS
Camel :: Catalog :: Console 0.7s SUCCESS
Camel :: Endpoint DSL n/a
Camel :: Integration Tests n/a
Camel :: JBang :: Core n/a
Camel :: JBang :: Plugin :: TUI n/a
Camel :: Launcher n/a

Top 20 slowest modules:

  • Camel :: JBang :: MCP (43.2s)
  • Camel :: AI :: LangChain4j :: Ingest (29.7s)
  • Camel :: JBang :: Plugin :: Validate (24.7s)
  • Camel :: YAML DSL :: Validator (23.5s)
  • Camel :: YAML DSL (20.6s)
  • Camel :: JBang :: Run (20.0s)
  • Camel :: AI :: Docling (19.8s)
  • Camel :: Catalog :: Camel Catalog (19.3s)
  • Camel :: Component DSL (15.7s)
  • Camel :: JBang :: Plugin :: Kubernetes (13.0s)
  • Camel :: Docs (12.1s)
  • Camel :: JBang :: Plugin :: Testing (10.6s)
  • Camel :: Kamelet Main (9.6s)
  • Camel :: Catalog :: Camel Report Maven Plugin (6.9s)
  • Camel :: YAML DSL :: Validator Maven Plugin (6.0s)
  • Camel :: Catalog :: Camel Route Parser (5.9s)
  • Camel :: YAML DSL :: Deserializers (5.9s)
  • Camel :: JBang :: Plugin :: Generate (4.3s)
  • Camel :: All Components Sync point (4.0s)
  • Camel :: Assembly (2.6s)

⚙️ View full build and test results

@davsclaus davsclaus added this to the 4.24.0 milestone Nov 13, 2026
@davsclaus
davsclaus merged commit 509fc85 into apache:main Nov 13, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants