janhoy commented on code in PR #4271: URL: https://github.com/apache/solr/pull/4271#discussion_r3248373863
########## dev-docs/ref-guide/antora.adoc: ########## @@ -61,6 +61,38 @@ Instead, update `antora.template.yaml`, and `gradlew buildLocalSite` will build The only reason you will likely need to change the `antora.template.yml` is if you are introducing new variables for dependency versions. +== Auto-generated CLI Reference Pages + +The `bin/solr` command-line tool documentation is partially auto-generated from the picocli `@Command`, `@Option`, and `@Parameters` annotations in the Java source. + +=== How it works + +For each command registered in `org.apache.solr.cli.SolrCLI` that uses picocli annotations, a dedicated AsciiDoc page is generated by `picocli.codegen.docgen.manpage.ManPageGenerator` and committed to: + +---- +solr/solr-ref-guide/modules/deployment-guide/pages/cli/ +---- + +The generated pages are post-processed to be Antora-compatible (correct page title, `:page-toclevels:` attribute, ASF license header, DO NOT EDIT notice). +The navigation section in `deployment-nav.adoc` between the `// CLI-DOCS-START` and `// CLI-DOCS-END` markers is also updated automatically. + +The main landing page `solr-control-script-reference.adoc` provides an overview of the available tools with links to each man-page. + +=== Gradle targets + +`./gradlew :solr:solr-ref-guide:generateCliDocs`:: +Regenerates all pages under `pages/cli/` from the current picocli annotations and updates the nav. +Run this after modifying any `@Command`, `@Option`, or `@Parameters` annotation in `solr/core/src/java/org/apache/solr/cli/`. + +`./gradlew :solr:solr-ref-guide:checkCliDocsUpToDate`:: +Verifies that the committed pages in `pages/cli/` are in sync with the current annotations. +This target is wired into `gradlew check`, so CI will catch annotation changes that were not followed by a `generateCliDocs` run. + +=== Adding docs for a new tool + +The new command will automatically appear in the generated pages and the navigation when running `gradlew generateCliDocs`. +You will need to tie it in to the `solr-control-script-reference.adoc` yourself. Review Comment: Yes, the control-script-reference page has still more work to do. I'll add another check box in the feature-branch PR for it... -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
