Apache Solr open-source search software
SOLR-18515: Preserve hyphenated picocli command names in generated CLI docs (#5068)
Jalaz Kumarc9c87d783685
diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradleindex 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.textdef 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 Setdef 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 Setreturn 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 SetrawFiles.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 Setdef 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.adocindex 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.adocindex 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.adocindex 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.adocindex 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.adocindex 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.adocindex 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.adocindex 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]