This is an automated email from the ASF dual-hosted git repository.
janhoy pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/main by this push:
new c9c87d78368 SOLR-18515: Preserve hyphenated picocli command names in
generated CLI docs (#5068)
c9c87d78368 is described below
commit c9c87d7836856ab1df01f9de50f2edb581b7535e
Author: Jalaz Kumar <[email protected]>
AuthorDate: Thu Oct 15 22:15:44 2026 +0530
SOLR-18515: Preserve hyphenated picocli command names in generated CLI docs
(#5068)
---
solr/solr-ref-guide/build.gradle | 60 ++++++++++++----------
.../modules/deployment-guide/deployment-nav.adoc | 10 ++--
.../modules/deployment-guide/pages/cli/index.adoc | 10 ++--
.../pages/cli/solr-package-add-key.adoc | 2 +-
.../pages/cli/solr-package-add-repo.adoc | 2 +-
.../pages/cli/solr-package-list-available.adoc | 2 +-
.../pages/cli/solr-package-list-deployed.adoc | 2 +-
.../pages/cli/solr-package-list-installed.adoc | 2 +-
8 files changed, 48 insertions(+), 42 deletions(-)
diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle
index 80ee1136386..c84ce7c4b10 100644
--- a/solr/solr-ref-guide/build.gradle
+++ b/solr/solr-ref-guide/build.gradle
@@ -609,16 +609,28 @@ def DO_NOT_EDIT_NOTICE = """\
"""
// Convert a generated filename stem (e.g. "solr-zk-ls") to an Antora page
title
-// e.g. "solr-zk-ls" -> "bin/solr zk ls"
-String cliFileNameToTitle(String baseName) {
- def parts = baseName.split('-')
- return "bin/solr " + parts.drop(1).join(' ')
-}
-
-// Return the short nav label for a command file (last segment of
dash-separated name)
-// e.g. "solr-zk-ls" -> "ls"
-String cliFileNameToNavLabel(String baseName) {
- return baseName.split('-').last()
+// A dash separated commands only when that prefix is itself a generated page,
+// so a hyphen inside the leaf name is kept
+// e.g. "solr-zk-ls" -> "bin/solr zk ls". "solr-package-add-key" -> "bin/solr
package add-key"
+String cliFileNameToTitle(String baseName, Set stems) {
+ return "bin/solr " + cliCommandPath(baseName, stems).join(' ')
+}
+
+// Tokens of the title after "solr". That last token is the nav label.
+// e.g. "solr-zk-ls" -> [zk, ls], "solr-package-add-key" -> [package, add-key]
+List<String> cliCommandPath(String baseName, Set stems) {
+ def cuts = [baseName.indexOf('-')]
+ for (def i = baseName.indexOf('-', cuts[0] + 1); i >= 0; i =
baseName.indexOf('-', i + 1)) {
+ if (stems.contains(baseName.substring(0, i))) {
+ cuts.add(i)
+ }
+ }
+ cuts.add(baseName.length())
+ def segments = []
+ for (def c = 0; c < cuts.size() - 1; c++) {
+ segments.add(baseName.substring(cuts[c] + 1, cuts[c + 1]))
+ }
+ return segments
}
// Strip "[...]" (optional groups) and "(...)" (required groups whose members
@@ -707,10 +719,10 @@ String markRequiredOptionsAndArgs(String content) {
// Post-process a raw ManPageGenerator AsciiDoc file for Antora compatibility.
// The title lives inside the man-section-header block, so we replace the whole
// header block with an Antora-compatible page title + attributes.
-String postProcessCliManPage(File rawFile, String asfHeader, String
doNotEditNotice, String experimentalNotice) {
+String postProcessCliManPage(File rawFile, Set stems, String asfHeader, String
doNotEditNotice, String experimentalNotice) {
def content = rawFile.text
def baseName = rawFile.name.replace('.adoc', '')
- def newTitle = cliFileNameToTitle(baseName)
+ def newTitle = cliFileNameToTitle(baseName, stems)
// Replace the entire man-section-header block (which contains
:doctype:manpage, the page title
// "= solr-start(1)", etc.) with our Antora-compatible title and page
attributes.
@@ -776,9 +788,10 @@ String buildCliCommandTable(File cliDir) {
def files = ((cliDir.listFiles() ?: []) as List<File>)
.findAll { it.name.startsWith('solr-') && it.name.endsWith('.adoc') }
.sort { it.name }
+ def stems = files.collect { it.name.replace('.adoc', '') } as Set
def rows = files.collect { file ->
def baseName = file.name.replace('.adoc', '')
- "|xref:cli/${file.name}[${cliFileNameToTitle(baseName)}]"
+ "|xref:cli/${file.name}[${cliFileNameToTitle(baseName, stems)}]"
}
return "[cols=\"1\",options=\"header\"]\n|===\n|Command\n\n" +
rows.join('\n') + "\n|==="
}
@@ -792,18 +805,9 @@ List<String> buildCliNavEntries(File cliDir) {
.sort { (it.name.replace('.adoc', '') + '\u0000') }
def stems = files.collect { it.name.replace('.adoc', '') } as Set
return files.collect { file ->
- def baseName = file.name.replace('.adoc', '')
- def label = cliFileNameToNavLabel(baseName)
- // Nest under the deepest ancestor that is itself a generated page.
Counting dashes instead
- // would mis-nest a command whose own name contains one, e.g. a future
"snapshot-create"
- // would be filed under a "solr-snapshot" page that does not exist.
- def depth = 0
- for (def stem = baseName; stem.contains('-'); ) {
- stem = stem.substring(0, stem.lastIndexOf('-'))
- if (stems.contains(stem)) {
- depth++
- }
- }
+ def path = cliCommandPath(file.name.replace('.adoc', ''), stems)
+ def label = path.last()
+ def depth = path.size() - 1
// Generated pages hang off cli/index.adoc, which itself sits under the
control script page,
// so the shallowest generated page is already three levels deep.
def stars = '*' * (depth + 3)
@@ -855,9 +859,10 @@ task generateCliDocs {
destDir.mkdirs()
def rawFiles = runManPageGenerator(rawOutputDir)
+ def stems = rawFiles.collect { it.name.replace('.adoc', '') } as Set
rawFiles.each { rawFile ->
- def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER,
DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
+ def processed = postProcessCliManPage(rawFile, stems,
ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
new File(destDir, rawFile.name).text = processed
}
@@ -910,10 +915,11 @@ task checkCliDocsUpToDate {
rawOutputDir.mkdirs()
def rawFiles = runManPageGenerator(rawOutputDir)
+ def stems = rawFiles.collect { it.name.replace('.adoc', '') } as Set
def issues = []
rawFiles.each { rawFile ->
- def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER,
DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
+ def processed = postProcessCliManPage(rawFile, stems,
ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE, EXPERIMENTAL_NOTICE)
def committed = new File(committedDir, rawFile.name)
if (!committed.exists()) {
issues << "MISSING committed file (new command): ${rawFile.name}"
diff --git a/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc
b/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc
index b001d404ba3..e22a51c7be1 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc
@@ -30,13 +30,13 @@
*** xref:cli/solr-export.adoc[export]
*** xref:cli/solr-healthcheck.adoc[healthcheck]
*** xref:cli/solr-package.adoc[package]
-**** xref:cli/solr-package-add-key.adoc[key]
-**** xref:cli/solr-package-add-repo.adoc[repo]
+**** xref:cli/solr-package-add-key.adoc[add-key]
+**** xref:cli/solr-package-add-repo.adoc[add-repo]
**** xref:cli/solr-package-deploy.adoc[deploy]
**** xref:cli/solr-package-install.adoc[install]
-**** xref:cli/solr-package-list-available.adoc[available]
-**** xref:cli/solr-package-list-deployed.adoc[deployed]
-**** xref:cli/solr-package-list-installed.adoc[installed]
+**** xref:cli/solr-package-list-available.adoc[list-available]
+**** xref:cli/solr-package-list-deployed.adoc[list-deployed]
+**** xref:cli/solr-package-list-installed.adoc[list-installed]
**** xref:cli/solr-package-undeploy.adoc[undeploy]
**** xref:cli/solr-package-uninstall.adoc[uninstall]
*** xref:cli/solr-post.adoc[post]
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc
index 318010391d5..fb8ea48e30e 100644
--- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc
+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/index.adoc
@@ -68,13 +68,13 @@ Any command not listed here is unavailable when the picocli
implementation is en
|xref:cli/solr-delete.adoc[bin/solr delete]
|xref:cli/solr-export.adoc[bin/solr export]
|xref:cli/solr-healthcheck.adoc[bin/solr healthcheck]
-|xref:cli/solr-package-add-key.adoc[bin/solr package add key]
-|xref:cli/solr-package-add-repo.adoc[bin/solr package add repo]
+|xref:cli/solr-package-add-key.adoc[bin/solr package add-key]
+|xref:cli/solr-package-add-repo.adoc[bin/solr package add-repo]
|xref:cli/solr-package-deploy.adoc[bin/solr package deploy]
|xref:cli/solr-package-install.adoc[bin/solr package install]
-|xref:cli/solr-package-list-available.adoc[bin/solr package list available]
-|xref:cli/solr-package-list-deployed.adoc[bin/solr package list deployed]
-|xref:cli/solr-package-list-installed.adoc[bin/solr package list installed]
+|xref:cli/solr-package-list-available.adoc[bin/solr package list-available]
+|xref:cli/solr-package-list-deployed.adoc[bin/solr package list-deployed]
+|xref:cli/solr-package-list-installed.adoc[bin/solr package list-installed]
|xref:cli/solr-package-undeploy.adoc[bin/solr package undeploy]
|xref:cli/solr-package-uninstall.adoc[bin/solr package uninstall]
|xref:cli/solr-package.adoc[bin/solr package]
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-key.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-key.adoc
index 801afac3091..d3627e3b970 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-key.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-key.adoc
@@ -19,7 +19,7 @@
// To update: modify the @Command/@Option annotations in the Java source, then
run:
// ./gradlew :solr:solr-ref-guide:generateCliDocs
-= bin/solr package add key
+= bin/solr package add-key
:page-toclevels: 2
[WARNING]
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-repo.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-repo.adoc
index 04f1eccd2fc..23fdc5e602f 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-repo.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-add-repo.adoc
@@ -19,7 +19,7 @@
// To update: modify the @Command/@Option annotations in the Java source, then
run:
// ./gradlew :solr:solr-ref-guide:generateCliDocs
-= bin/solr package add repo
+= bin/solr package add-repo
:page-toclevels: 2
[WARNING]
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-available.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-available.adoc
index 83110eb433d..2f3aa96e0e5 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-available.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-available.adoc
@@ -19,7 +19,7 @@
// To update: modify the @Command/@Option annotations in the Java source, then
run:
// ./gradlew :solr:solr-ref-guide:generateCliDocs
-= bin/solr package list available
+= bin/solr package list-available
:page-toclevels: 2
[WARNING]
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-deployed.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-deployed.adoc
index ecd8cdfb609..988f0e0768b 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-deployed.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-deployed.adoc
@@ -19,7 +19,7 @@
// To update: modify the @Command/@Option annotations in the Java source, then
run:
// ./gradlew :solr:solr-ref-guide:generateCliDocs
-= bin/solr package list deployed
+= bin/solr package list-deployed
:page-toclevels: 2
[WARNING]
diff --git
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-installed.adoc
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-installed.adoc
index 216b3e58bfb..f57b076cc22 100644
---
a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-installed.adoc
+++
b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package-list-installed.adoc
@@ -19,7 +19,7 @@
// To update: modify the @Command/@Option annotations in the Java source, then
run:
// ./gradlew :solr:solr-ref-guide:generateCliDocs
-= bin/solr package list installed
+= bin/solr package list-installed
:page-toclevels: 2
[WARNING]
