oscerd opened a new pull request, #20838:
URL: https://github.com/apache/camel/pull/20838
# Description
This was on my mind from a while and hopefully it would be useful.
This PR adds automatic documentation generation for Camel JBang CLI commands
during the Maven build process. Similar to how component options are
auto-generated, this feature scans Picocli-annotated command classes and
generates AsciiDoc documentation pages with proper command hierarchy support.
Things done
1. Created model classes for command metadata
- JBangCommandModel.java - represents commands with their options and
subcommands
- Added JSON serialization/deserialization in JsonMapper.java
2. Created Maven mojos for scanning and doc generation
- PrepareCamelJBangCommandsMojo (goal: prepare-jbang-commands) - scans
command classes using Roaster, parses Picocli annotations, builds command
hierarchy from CamelJBangMain.java using indentation-based parsing, and
generates camel-jbang-commands-metadata.json
- PrepareCamelJBangCommandsDocMojo (goal: prepare-jbang-commands-doc) -
reads JSON metadata and generates AsciiDoc pages using MVEL templates, with
protection for manually-maintained files
3. Created MVEL templates
- jbang-commands.mvel - generates the command index page
- jbang-command-page.mvel - generates individual command pages with
usage, options, and subcommands sections
4. Updated build configuration and navigation
- Added plugin executions to camel-jbang-core/pom.xml
- Added navigation entry in nav.adoc
- Added link from main camel-jbang.adoc to command reference
- Added **/*.mvel to license-maven-plugin exclusions in root pom.xml
For the Parsing I used code generated by Claude code, because it was a bit
troublesome to detect subcommands.
# Target
- [x] I checked that the commit is targeting the correct branch (Camel 4
uses the `main` branch)
# Tracking
- [x] If this is a large change, bug fix, or code improvement, I checked
there is a [JIRA issue](https://issues.apache.org/jira/browse/CAMEL) filed for
the change (usually before you start working on it).
<!--
# *Note*: trivial changes like, typos, minor documentation fixes and other
small items do not require a JIRA issue. In this case your pull request should
address just this issue, without pulling in other changes.
-->
# Apache Camel coding standards and style
- [x] I checked that each commit in the pull request has a meaningful
subject line and body.
<!--
If you're unsure, you can format the pull request title like `[CAMEL-XXX]
Fixes bug in camel-file component`, where you replace `CAMEL-XXX` with the
appropriate JIRA issue.
-->
- [x] I have run `mvn clean install -DskipTests` locally from root folder
and I have committed all auto-generated changes.
<!--
You can run the aforementioned command in your module so that the build
auto-formats your code. This will also be verified as part of the checks and
your PR may be rejected if if there are uncommited changes after running `mvn
clean install -DskipTests`.
You can learn more about the contribution guidelines at
https://github.com/apache/camel/blob/main/CONTRIBUTING.md
-->
--
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]
