From d6812b159d9b51a4e919f40e73b148af453c9605 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 8 Apr 2026 12:13:48 +0200 Subject: [PATCH 1/4] SOLR-17697 Ref-guide documentation for new picocli commands --- solr/core/build.gradle | 20 ++ solr/solr-ref-guide/build.gradle | 208 ++++++++++++++++++ .../deployment-guide/deployment-nav.adoc | 15 ++ .../pages/cli/solr-start.adoc | 125 +++++++++++ .../pages/cli/solr-status.adoc | 85 +++++++ .../deployment-guide/pages/cli/solr-stop.adoc | 80 +++++++ .../pages/cli/solr-version.adoc | 63 ++++++ .../pages/cli/solr-zk-cp.adoc | 99 +++++++++ .../pages/cli/solr-zk-downconfig.adoc | 85 +++++++ .../pages/cli/solr-zk-ls.adoc | 86 ++++++++ .../pages/cli/solr-zk-mkroot.adoc | 87 ++++++++ .../pages/cli/solr-zk-mv.adoc | 91 ++++++++ .../pages/cli/solr-zk-rm.adoc | 86 ++++++++ .../pages/cli/solr-zk-upconfig.adoc | 85 +++++++ .../pages/cli/solr-zk-updateacls.adoc | 84 +++++++ .../deployment-guide/pages/cli/solr-zk.adoc | 92 ++++++++ .../pages/solr-control-script-reference.adoc | 67 ++++++ 17 files changed, 1458 insertions(+) create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc create mode 100644 solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc diff --git a/solr/core/build.gradle b/solr/core/build.gradle index 398a0a2a2ca4..721aa9678072 100644 --- a/solr/core/build.gradle +++ b/solr/core/build.gradle @@ -210,3 +210,23 @@ dependencies { testImplementation libs.opentelemetry.sdk.testing testImplementation libs.dropwizard.metrics.core } + +// Expose a configuration for CLI doc generation in the solr-ref-guide project. +// This bundles the full runtime classpath plus picocli-codegen (ManPageGenerator) +// and the compiled CLI classes so that generateCliDocs can invoke ManPageGenerator. +configurations { + cliDocsRuntime { + canBeResolved = true + canBeConsumed = true + // Inherit all runtime dependencies (implementation + runtimeOnly transitively) + extendsFrom configurations.runtimeClasspath + } +} + +dependencies { + // picocli-codegen provides ManPageGenerator (not in runtime, only needed for doc gen) + cliDocsRuntime libs.picocli.codegen + // Include the compiled CLI classes themselves + cliDocsRuntime files(sourceSets.main.output.classesDirs) + cliDocsRuntime files(sourceSets.main.output.resourcesDir) +} diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 5b53514d698a..0127ca5c47b1 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -60,11 +60,16 @@ configurations { officialPlaybook localPlaybook localJavadocs + cliClasspath { + canBeResolved = true + canBeConsumed = false + } } dependencies { localJavadocs project(path: ":solr:documentation", configuration: 'javadocs') localJavadocs project(path: ":solr:documentation", configuration: 'site') + cliClasspath project(path: ':solr:core', configuration: 'cliDocsRuntime') } ext { @@ -540,6 +545,209 @@ task buildOfficialSite(type: NpxTask) { } } +/* + CLI Documentation Generation from Picocli Annotations + Generates per-command AsciiDoc reference pages for the Antora ref guide. + Usage: + ./gradlew :solr:solr-ref-guide:generateCliDocs -- regenerate pages/cli/ + ./gradlew :solr:solr-ref-guide:checkCliDocsUpToDate -- verify in-sync (also run by check) + */ + +def ASF_LICENSE_HEADER = """\ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +""" + +def DO_NOT_EDIT_NOTICE = """\ +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs +""" + +// 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() +} + +// 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) { + def content = rawFile.text + def baseName = rawFile.name.replace('.adoc', '') + def newTitle = cliFileNameToTitle(baseName) + + // 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. + content = content.replaceAll( + /(?s)\/\/ tag::picocli-generated-man-section-header\[\].*?\/\/ end::picocli-generated-man-section-header\[\]\n\n?/, + "= ${newTitle}\n:page-toclevels: 2\n\n") + + // ManPageGenerator renders the command's qualified name as "bin/solr-start" (parent-dash-child). + // Replace occurrences of that with the correct spaced form "bin/solr start". + def picocliQualifiedName = 'bin/solr-' + baseName.substring('solr-'.length()) + content = content.replace(picocliQualifiedName, newTitle) + + // Strip the outer full-manpage tag wrappers + content = content.replace("// tag::picocli-generated-full-manpage[]\n", '') + content = content.replace("// end::picocli-generated-full-manpage[]\n", '') + + return asfHeader + doNotEditNotice + "\n" + content.stripTrailing() + "\n" +} + +// Build the CLI sub-page nav entries from the generated .adoc files in destDir. +// Returns a list of nav lines like "** xref:cli/solr-start.adoc[start]" +List buildCliNavEntries(File cliDir) { + // Sort so that parent commands always precede their children. + // The trick: append '\u0000' (NUL, ASCII 0) to the stem before sorting. + // NUL < '-' (ASCII 45), so "solr-zk\0" < "solr-zk-cp\0", placing the parent first. + def files = ((cliDir.listFiles() ?: []) as List) + .findAll { it.name.endsWith('.adoc') } + .sort { (it.name.replace('.adoc', '') + '\u0000') } + return files.collect { file -> + def baseName = file.name.replace('.adoc', '') + def parts = baseName.split('-') + // depth: "solr-start" has 2 parts → "**", "solr-zk-ls" has 3 parts → "***" + def stars = '*' * parts.length + def label = cliFileNameToNavLabel(baseName) + "${stars} xref:cli/${file.name}[${label}]" + } +} + +// Run ManPageGenerator and return the set of generated files (excluding the top-level solr.adoc). +// Because SolrCLI is annotated @Command(name="bin/solr"), ManPageGenerator writes all files into +// a "bin/" subdirectory of outputDir (e.g. outputDir/bin/solr-start.adoc). +List runManPageGenerator(File outputDir) { + // Pre-create the "bin/" subdir so ManPageGenerator can write into it + def binDir = new File(outputDir, "bin") + binDir.mkdirs() + + javaexec { + classpath = configurations.cliClasspath + mainClass = 'picocli.codegen.docgen.manpage.ManPageGenerator' + args = ['--outdir', outputDir.absolutePath, 'org.apache.solr.cli.SolrCLI'] + } + + // All generated files land in /bin/; exclude solr.adoc (the top-level parent page) + return (binDir.listFiles() as List) + .findAll { f -> f.name.endsWith('.adoc') && f.name != 'solr.adoc' } + .sort { it.name } +} + +task generateCliDocs { + group = 'generation' + description = 'Regenerate CLI reference pages in pages/cli/ from picocli annotations.' + + dependsOn ':solr:core:classes' + + def rawOutputDir = file("${buildDir}/generated-cli-docs-raw") + def destDir = file("modules/deployment-guide/pages/cli") + def navFile = file("modules/deployment-guide/deployment-nav.adoc") + + inputs.files(configurations.cliClasspath) + outputs.dir(destDir) + + doLast { + rawOutputDir.mkdirs() + destDir.mkdirs() + + def rawFiles = runManPageGenerator(rawOutputDir) + + rawFiles.each { rawFile -> + def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE) + new File(destDir, rawFile.name).text = processed + } + + // Update the CLI nav section in deployment-nav.adoc between marker comments + def navContent = navFile.text + if (navContent.contains('// CLI-DOCS-START')) { + def navEntries = buildCliNavEntries(destDir).join('\n') + def replacement = "// CLI-DOCS-START\n* xref:solr-control-script-reference.adoc[]\n${navEntries}\n// CLI-DOCS-END" + navContent = navContent.replaceAll(/(?s)\/\/ CLI-DOCS-START.*?\/\/ CLI-DOCS-END/, replacement) + navFile.text = navContent + } else { + logger.warn("deployment-nav.adoc does not contain // CLI-DOCS-START marker; nav not updated.") + } + + logger.lifecycle("Generated ${rawFiles.size()} CLI doc pages in ${destDir}") + } +} + +task checkCliDocsUpToDate { + group = 'verification' + description = 'Verify that pages/cli/ CLI docs are in sync with picocli annotations.' + + dependsOn ':solr:core:classes' + + def rawOutputDir = file("${buildDir}/generated-cli-docs-check") + def committedDir = file("modules/deployment-guide/pages/cli") + + inputs.files(configurations.cliClasspath) + inputs.dir(committedDir) + + doLast { + rawOutputDir.mkdirs() + + def rawFiles = runManPageGenerator(rawOutputDir) + def issues = [] + + rawFiles.each { rawFile -> + def processed = postProcessCliManPage(rawFile, ASF_LICENSE_HEADER, DO_NOT_EDIT_NOTICE) + def committed = new File(committedDir, rawFile.name) + if (!committed.exists()) { + issues << "MISSING committed file (new command): ${rawFile.name}" + } else { + def processedNorm = processed.replace('\r\n', '\n') + def committedNorm = committed.text.replace('\r\n', '\n') + if (processedNorm != committedNorm) { + issues << "OUT OF DATE: ${rawFile.name}" + } + } + } + + // Check for committed pages that are no longer generated (deleted commands) + if (committedDir.exists()) { + def generatedNames = rawFiles.collect { it.name }.toSet() + ((committedDir.listFiles() ?: []) as List).findAll { it.name.endsWith('.adoc') }.each { committed -> + if (!generatedNames.contains(committed.name)) { + issues << "STALE (command removed): ${committed.name}" + } + } + } + + if (!issues.isEmpty()) { + throw new GradleException( + "CLI docs are out of date. Run './gradlew :solr:solr-ref-guide:generateCliDocs' to regenerate.\n" + + "Issues:\n" + issues.collect { " - ${it}" }.join('\n')) + } + logger.lifecycle("CLI docs are up to date.") + } +} + +check.dependsOn checkCliDocsUpToDate + /* Compiling, Testing and Validation for the java examples in the Solr Ref Guide */ 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 55301601e3e0..2a5069735177 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc @@ -17,7 +17,22 @@ .Deployment Guide +// CLI-DOCS-START * xref:solr-control-script-reference.adoc[] +** xref:cli/solr-start.adoc[start] +** xref:cli/solr-status.adoc[status] +** xref:cli/solr-stop.adoc[stop] +** xref:cli/solr-version.adoc[version] +** xref:cli/solr-zk.adoc[zk] +*** xref:cli/solr-zk-cp.adoc[cp] +*** xref:cli/solr-zk-downconfig.adoc[downconfig] +*** xref:cli/solr-zk-ls.adoc[ls] +*** xref:cli/solr-zk-mkroot.adoc[mkroot] +*** xref:cli/solr-zk-mv.adoc[mv] +*** xref:cli/solr-zk-rm.adoc[rm] +*** xref:cli/solr-zk-upconfig.adoc[upconfig] +*** xref:cli/solr-zk-updateacls.adoc[updateacls] +// CLI-DOCS-END * Installation & Deployment ** xref:system-requirements.adoc[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc new file mode 100644 index 000000000000..4080ea598dbe --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc @@ -0,0 +1,125 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr start +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr start - Starts Solr in standalone or SolrCloud mode. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr start* [*-fhqVy*] [*--force*] [*--user-managed*] [*--verbose*] + [*--data-home*=__] [*-e*=__] + [*--example-dir*=__] [*--host*=__] [*-j*=__] + [*--jvm-opts*=__] [*-m*=__] [*-p*=__] + [*--prompt-inputs*=__] [*--server-dir*=__] + [*--solr-home*=__] [*-z*=__] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Starts Solr in standalone or SolrCloud mode. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*--data-home*=__:: + Set solr.data.home system property for index data storage; default is solr.solr.home + +*-e*, *--example*=__:: + Run an example: cloud, techproducts, schemaless, films + +*--example-dir*=__:: + Override the directory containing example configurations used when running examples with --example + +*-f*, *--foreground*:: + Start Solr in foreground; default is background with logs to solr-PORT-console.log + +*--force*:: + Override warning when attempting to start Solr as root user + +*-h*, *--help*:: + Show this help message and exit. + +*--host*=__:: + Specify the hostname for this Solr instance + +*-j*, *--jettyconfig*=__:: + Additional Jetty parameters, e.g., -j "--include-jetty-dir=/etc/jetty/custom/server/" + +*--jvm-opts*=__:: + Additional JVM parameters, e.g., --jvm-opts "-verbose:gc" + +*-m*, *--memory*=__:: + Set JVM heap size, e.g., -m 4g sets -Xms4g -Xmx4g; default is 512m + +*-p*, *--port*=__:: + Specify the Solr HTTP port; default is 8983. STOP_PORT=($SOLR_PORT-1000), RMI_PORT=($SOLR_PORT+10000) + +*--prompt-inputs*=__:: + Don't prompt for input; comma-delimited list of inputs to use when running examples that accept user input + +*-q*, *--quiet*:: + Set log level to WARN (quiet); default is INFO + +*--server-dir*=__:: + Specify the Solr server directory; default is 'server' + +*--solr-home*=__:: + Set solr.solr.home system property; default is 'server/solr'. Ignored in examples mode + +*--user-managed*:: + Start Solr in standalone mode. Default is SolrCloud (ZooKeeper) mode. + +*-V*, *--version*:: + Print version information and exit. + +*--verbose*:: + Set log level to DEBUG (verbose); default is INFO + +*-y*, *--no-prompt*:: + Don't prompt for input; accept all defaults when running examples + +*-z*, *--zk-host*=__:: + Zookeeper connection string; default is to start an embedded ZooKeeper on PORT+10000 + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc new file mode 100644 index 000000000000..250591ee1d75 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc @@ -0,0 +1,85 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr status +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr status - Get the status of a Solr server. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr status* [*-hvV*] [*--short*] [*--max-wait-secs*=__] [*-p*=__] + [*-s*=__] [*-u*=__] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Get the status of a Solr server. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*--max-wait-secs*=__:: + Wait up to the specified number of seconds to see Solr running. + +*-p*, *--port*=__:: + Port on localhost to check status for + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if that's not known + +*--short*:: + Short format. Prints one URL per line for running instances + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc new file mode 100644 index 000000000000..e4218c6fd955 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc @@ -0,0 +1,80 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr stop +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr stop - Stops Solr. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr stop* [*-hV*] [*--all*] [*--verbose*] [*-k*=__] [*-p*=__] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Stops Solr. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*--all*:: + Find and stop all running Solr servers on this host + +*-h*, *--help*:: + Show this help message and exit. + +*-k*, *--key*=__:: + Stop key; default is solrrocks + +*-p*, *--port*=__:: + Specify the port the Solr HTTP listener is bound to. ++ +The STOP_PORT is derived as ($SOLR_PORT-1000). + +*-V*, *--version*:: + Print version information and exit. + +*--verbose*:: + Enable verbose mode. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc new file mode 100644 index 000000000000..6947ebbbcbcf --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc @@ -0,0 +1,63 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr version +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr version - Prints the Solr version. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr version* [*-v*] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Prints the Solr version. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-v*, *--verbose*:: + Enable verbose mode. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc new file mode 100644 index 000000000000..16a7fcf80e79 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc @@ -0,0 +1,99 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk cp +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk cp - Copy files or folders to/from ZooKeeper or ZooKeeper to ZooKeeper. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk cp* [*-hrvV*] [*-s*=__] [*--solr-home*=_DIR_] [*-u*=__] + [*-z*=__] __ __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Copy files or folders to/from ZooKeeper or ZooKeeper to ZooKeeper. + +, : [file:][/]path/to/local/file or zk:/path/to/zk/node +NOTE: and may both be ZooKeeper resources prefixed by 'zk:' +When is a zk resource, may be '.' +If ends with '/', then will be a local folder or parent znode +and the last element of the path will be appended unless also ends in a slash. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-r*, *--recursive*:: + Apply the command recursively. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*--solr-home*=_DIR_:: + Required to look up configuration for compressing state.json. + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + Source path: [file:][/]path/to/local/file or zk:/path/to/zk/node. + +__:: + Destination path: [file:][/]path/to/local/file or zk:/path/to/zk/node. + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc new file mode 100644 index 000000000000..bd5807a30351 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc @@ -0,0 +1,85 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk downconfig +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk downconfig - Download a configset from ZooKeeper to the local filesystem. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk downconfig* [*-hvV*] *-d*=_DIR_ *-n*=__ [*-s*=__] + [*-u*=__] [*-z*=__] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Download a configset from ZooKeeper to the local filesystem. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-d*, *--conf-dir*=_DIR_:: + Local directory with configs. + +*-h*, *--help*:: + Show this help message and exit. + +*-n*, *--conf-name*=__:: + Configset name in ZooKeeper. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc new file mode 100644 index 000000000000..2c6a9cd1b7bb --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc @@ -0,0 +1,86 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk ls +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk ls - List the contents of a ZooKeeper node. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk ls* [*-hrvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +List the contents of a ZooKeeper node. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-r*, *--recursive*:: + Apply the command recursively. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + The path of the ZooKeeper znode path to list. + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc new file mode 100644 index 000000000000..ab820c5c254d --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc @@ -0,0 +1,87 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk mkroot +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk mkroot - Make a znode in ZooKeeper with no data. Can be used to make a path of arbitrary depth but primarily intended to create a 'chroot'. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk mkroot* [*-hvV*] [*--fail-on-exists*[=__]] [*-s*=__] + [*-u*=__] [*-z*=__] __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Make a znode in ZooKeeper with no data. Can be used to make a path of arbitrary depth but primarily intended to create a 'chroot'. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*--fail-on-exists*[=__]:: + Raise an error if the znode already exists. Defaults to false. + +*-h*, *--help*:: + Show this help message and exit. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + The ZooKeeper znode path to create. + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc new file mode 100644 index 000000000000..6df8366ad530 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc @@ -0,0 +1,91 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk mv +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk mv - Move (rename) a znode on ZooKeeper. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk mv* [*-hvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ + __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Move (rename) a znode on ZooKeeper. + +, : ZooKeeper nodes, the 'zk:' prefix is optional. +If ends with '/', then will be a parent znode +and the last element of the path will be appended. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + Source ZooKeeper znode path (zk: prefix optional). + +__:: + Destination ZooKeeper znode path (zk: prefix optional). + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc new file mode 100644 index 000000000000..11d7bbbfca5c --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc @@ -0,0 +1,86 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk rm +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk rm - Remove a znode from ZooKeeper. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk rm* [*-hrvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Remove a znode from ZooKeeper. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-r*, *--recursive*:: + Apply the command recursively. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + The ZooKeeper znode path to remove (zk: prefix optional). + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc new file mode 100644 index 000000000000..49a44322da11 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc @@ -0,0 +1,85 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk upconfig +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk upconfig - Upload a configset from the local filesystem to ZooKeeper. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk upconfig* [*-hvV*] *-d*=_DIR_ *-n*=__ [*-s*=__] + [*-u*=__] [*-z*=__] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Upload a configset from the local filesystem to ZooKeeper. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-d*, *--conf-dir*=_DIR_:: + Local directory with configs. + +*-h*, *--help*:: + Show this help message and exit. + +*-n*, *--conf-name*=__:: + Configset name in ZooKeeper. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc new file mode 100644 index 000000000000..6d8e983c83a3 --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc @@ -0,0 +1,84 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk updateacls +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk updateacls - Update ACLs for a ZooKeeper znode. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk updateacls* [*-hvV*] [*-s*=__] [*-u*=__] [*-z*=__] + __ + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Update ACLs for a ZooKeeper znode. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-s*, *--solr-url*=__:: + Base Solr URL, which can be used to determine the zk-host if --zk-host is not known + +*-u*, *--credentials*=__:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*-v*, *--verbose*:: + Enable verbose mode. + +*-V*, *--version*:: + Print version information and exit. + +*-z*, *--zk-host*=__:: + Zookeeper connection string; unnecessary if ZK_HOST is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +== Arguments + +__:: + The ZooKeeper znode path to update ACLs for. + +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc new file mode 100644 index 000000000000..6b60a6c3827a --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc @@ -0,0 +1,92 @@ +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// DO NOT EDIT -- this page is auto-generated from picocli annotations. +// To update: modify the @Command/@Option annotations in the Java source, then run: +// ./gradlew :solr:solr-ref-guide:generateCliDocs + += bin/solr zk +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr zk - Sub commands for working with ZooKeeper. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +*bin/solr zk* [*-hV*] [COMMAND] + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Sub commands for working with ZooKeeper. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-h*, *--help*:: + Show this help message and exit. + +*-V*, *--version*:: + Print version information and exit. + +// end::picocli-generated-man-section-options[] + +// tag::picocli-generated-man-section-arguments[] +// end::picocli-generated-man-section-arguments[] + +// tag::picocli-generated-man-section-commands[] +== Commands + +xref:bin/solr zk-downconfig.adoc[*downconfig*]:: + Download a configset from ZooKeeper to the local filesystem. + +xref:bin/solr zk-upconfig.adoc[*upconfig*]:: + Upload a configset from the local filesystem to ZooKeeper. + +xref:bin/solr zk-cp.adoc[*cp*]:: + Copy files or folders to/from ZooKeeper or ZooKeeper to ZooKeeper. + +xref:bin/solr zk-ls.adoc[*ls*]:: + List the contents of a ZooKeeper node. + +xref:bin/solr zk-mkroot.adoc[*mkroot*]:: + Make a znode in ZooKeeper with no data. Can be used to make a path of arbitrary depth but primarily intended to create a 'chroot'. + +xref:bin/solr zk-mv.adoc[*mv*]:: + Move (rename) a znode on ZooKeeper. + +xref:bin/solr zk-rm.adoc[*rm*]:: + Remove a znode from ZooKeeper. + +xref:bin/solr zk-updateacls.adoc[*updateacls*]:: + Update ACLs for a ZooKeeper znode. + +// end::picocli-generated-man-section-commands[] + +// tag::picocli-generated-man-section-exit-status[] +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +// end::picocli-generated-man-section-footer[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc index a7348059cc2e..7da11daa5085 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc @@ -25,6 +25,47 @@ The SolrCLI makes Solr easier to work with by providing simple commands and opti More examples of SolrCLI in use are available throughout this Guide, particularly in the sections xref:installing-solr.adoc#starting-solr[Starting Solr] and xref:getting-started:tutorial-solrcloud.adoc[]. +== Command Reference + +The table below lists all available `bin/solr` commands. +Commands marked with (✓) have dedicated reference pages auto-generated from source annotations; others are documented inline below. + +[cols="1,1,3",options="header"] +|=== +|Command |Sub-command |Description + +|xref:cli/solr-start.adoc[start] |(✓) |Start Solr +|restart | |Restart a running Solr node +|xref:cli/solr-stop.adoc[stop] |(✓) |Stop a running Solr node +|xref:cli/solr-status.adoc[status] |(✓) |Display status of running Solr nodes +|xref:cli/solr-version.adoc[version] |(✓) |Print Solr version +|create | |Create a collection or core +|delete | |Delete a collection or core +|healthcheck | |Generate a JSON-formatted health report for a collection +|assert | |Assert conditions about the Solr installation +|auth | |Configure authentication +|config | |Set or unset configuration properties +|export | |Export documents from a collection +|import | |Import documents into a collection +|api | |Interact with the Solr API +|package | |Manage Solr packages +|postlogs | |Index log data +|stream | |Execute a streaming expression +|snapshot-create | |Create a snapshot of a collection +|snapshot-delete | |Delete a snapshot +|snapshot-list | |List available snapshots +|snapshot-describe | |Describe a snapshot +|snapshot-export | |Export a snapshot +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-upconfig.adoc[upconfig] (✓) |Upload a configset to ZooKeeper +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-downconfig.adoc[downconfig] (✓) |Download a configset from ZooKeeper +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-cp.adoc[cp] (✓) |Copy files to/from ZooKeeper +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-ls.adoc[ls] (✓) |List ZooKeeper node contents +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-rm.adoc[rm] (✓) |Remove a ZooKeeper path +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-mv.adoc[mv] (✓) |Move a ZooKeeper node +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-mkroot.adoc[mkroot] (✓) |Create a root ZooKeeper path +|xref:cli/solr-zk.adoc[zk] |xref:cli/solr-zk-updateacls.adoc[updateacls] (✓) |Update ZooKeeper ACLs +|=== + == Starting and Stopping === Start and Restart @@ -46,6 +87,8 @@ When using the `restart` command, you must pass all of the parameters you initia Behind the scenes, a stop request is initiated, so Solr will be stopped before being started again. If no nodes are already running, restart will skip the step to stop and proceed to starting Solr. +For a full list of options see xref:cli/solr-start.adoc[]. + ==== Start Parameters The `bin/solr` script provides many options to allow you to customize the server in common ways, such as changing the listening port. @@ -394,6 +437,8 @@ The command will wait up to 180 seconds for Solr to stop gracefully and then wil `bin/solr stop --help` +For a full list of options see xref:cli/solr-stop.adoc[]. + ==== Stop Parameters `-p `:: @@ -453,6 +498,8 @@ $ bin/solr --version X.Y.0 ---- +For a full list of options see xref:cli/solr-version.adoc[]. + === Status The `status` command displays basic JSON-formatted status information for all locally running Solr servers. @@ -492,6 +539,8 @@ Solr process 39827 running on port 8865 "collections":"2"}} ---- +For a full list of options see xref:cli/solr-status.adoc[]. + === Assert The `assert` command checks common issues with Solr installations. @@ -1167,6 +1216,24 @@ All `bin/solr zk` sub-commands require a ZooKeeper connection string to function This means if you have `ZK_HOST` configured in your environment, you do not need to pass the `-z` option to every command. +=== ZooKeeper Subcommands + +All `bin/solr zk` subcommands have dedicated reference pages with full option documentation: + +[cols="1,3",options="header"] +|=== +|Command |Description + +|xref:cli/solr-zk-upconfig.adoc[upconfig] |Upload a configuration set to ZooKeeper +|xref:cli/solr-zk-downconfig.adoc[downconfig] |Download a configuration set from ZooKeeper +|xref:cli/solr-zk-cp.adoc[cp] |Copy files between the local file system and ZooKeeper, or between two ZooKeeper paths +|xref:cli/solr-zk-ls.adoc[ls] |List the contents of a ZooKeeper node +|xref:cli/solr-zk-rm.adoc[rm] |Remove a ZooKeeper path +|xref:cli/solr-zk-mv.adoc[mv] |Move a ZooKeeper node from one path to another +|xref:cli/solr-zk-mkroot.adoc[mkroot] |Create a root ZooKeeper path +|xref:cli/solr-zk-updateacls.adoc[updateacls] |Update Access Control on a ZooKeeper path +|=== + === Upload a Configuration Set Use the `zk upconfig` command to upload one of the pre-configured configuration sets or a customized configuration set to ZooKeeper. From e46d29794bf9599d6e88e764421b9dd21b264965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 8 Apr 2026 12:55:44 +0200 Subject: [PATCH 2/4] Add dev-docs --- dev-docs/ref-guide/antora.adoc | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/dev-docs/ref-guide/antora.adoc b/dev-docs/ref-guide/antora.adoc index a363cb3fe46e..7ed1debefc06 100644 --- a/dev-docs/ref-guide/antora.adoc +++ b/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. + == Building the HTML Site A Gradle target `gradlew buildLocalSite` will build the full HTML site (found in `solr/solr-ref-guide/build/site`). From dd530d5284d5de829820d2b3599fd85bc905567a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Wed, 8 Apr 2026 13:07:22 +0200 Subject: [PATCH 3/4] Fix synopsis by printing it in a code block --- solr/solr-ref-guide/build.gradle | 13 +++++++++++++ .../deployment-guide/pages/cli/solr-start.adoc | 14 ++++++++------ .../deployment-guide/pages/cli/solr-status.adoc | 6 ++++-- .../deployment-guide/pages/cli/solr-stop.adoc | 4 +++- .../deployment-guide/pages/cli/solr-version.adoc | 4 +++- .../deployment-guide/pages/cli/solr-zk-cp.adoc | 6 ++++-- .../pages/cli/solr-zk-downconfig.adoc | 6 ++++-- .../deployment-guide/pages/cli/solr-zk-ls.adoc | 4 +++- .../deployment-guide/pages/cli/solr-zk-mkroot.adoc | 6 ++++-- .../deployment-guide/pages/cli/solr-zk-mv.adoc | 6 ++++-- .../deployment-guide/pages/cli/solr-zk-rm.adoc | 4 +++- .../pages/cli/solr-zk-upconfig.adoc | 6 ++++-- .../pages/cli/solr-zk-updateacls.adoc | 6 ++++-- .../deployment-guide/pages/cli/solr-zk.adoc | 4 +++- 14 files changed, 64 insertions(+), 25 deletions(-) diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 0127ca5c47b1..b06d28d25c79 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -610,6 +610,19 @@ String postProcessCliManPage(File rawFile, String asfHeader, String doNotEditNot def picocliQualifiedName = 'bin/solr-' + baseName.substring('solr-'.length()) content = content.replace(picocliQualifiedName, newTitle) + // Wrap the synopsis paragraph in a literal block to preserve line breaks and indentation. + // ManPageGenerator generates a plain paragraph with picocli AsciiDoc marks (*bold*, _italic_) + // which Asciidoctor collapses to a single line. A `....` literal block preserves whitespace + // but does not render inline formatting, so we strip the marks for a clean monospace output. + content = content.replaceAll( + /(?s)(== Synopsis\n\n)(.*?)(\n\n\/\/ end::picocli-generated-man-section-synopsis\[\])/ + ) { List m -> + def synopsis = m[2] + .replaceAll(/\*([^*]+)\*/, '$1') // *bold* → plain + .replaceAll(/_([^_]+)_/, '$1') // _italic_ → plain + "${m[1]}....\n${synopsis}\n....${m[3]}" + } + // Strip the outer full-manpage tag wrappers content = content.replace("// tag::picocli-generated-full-manpage[]\n", '') content = content.replace("// end::picocli-generated-full-manpage[]\n", '') diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc index 4080ea598dbe..571b2cb4a2d8 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-start.adoc @@ -31,12 +31,14 @@ bin/solr start - Starts Solr in standalone or SolrCloud mode. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr start* [*-fhqVy*] [*--force*] [*--user-managed*] [*--verbose*] - [*--data-home*=__] [*-e*=__] - [*--example-dir*=__] [*--host*=__] [*-j*=__] - [*--jvm-opts*=__] [*-m*=__] [*-p*=__] - [*--prompt-inputs*=__] [*--server-dir*=__] - [*--solr-home*=__] [*-z*=__] +.... +bin/solr start [-fhqVy] [--force] [--user-managed] [--verbose] + [--data-home=] [-e=] + [--example-dir=] [--host=] [-j=] + [--jvm-opts=] [-m=] [-p=] + [--prompt-inputs=] [--server-dir=] + [--solr-home=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc index 250591ee1d75..5489562a9a8b 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-status.adoc @@ -31,8 +31,10 @@ bin/solr status - Get the status of a Solr server. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr status* [*-hvV*] [*--short*] [*--max-wait-secs*=__] [*-p*=__] - [*-s*=__] [*-u*=__] +.... +bin/solr status [-hvV] [--short] [--max-wait-secs=] [-p=] + [-s=] [-u=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc index e4218c6fd955..1ab34bfb5d28 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-stop.adoc @@ -31,7 +31,9 @@ bin/solr stop - Stops Solr. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr stop* [*-hV*] [*--all*] [*--verbose*] [*-k*=__] [*-p*=__] +.... +bin/solr stop [-hV] [--all] [--verbose] [-k=] [-p=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc index 6947ebbbcbcf..2cb427b2e233 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-version.adoc @@ -31,7 +31,9 @@ bin/solr version - Prints the Solr version. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr version* [*-v*] +.... +bin/solr version [-v] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc index 16a7fcf80e79..78fd0cdefc15 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-cp.adoc @@ -31,8 +31,10 @@ bin/solr zk cp - Copy files or folders to/from ZooKeeper or ZooKeeper to ZooKeep // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk cp* [*-hrvV*] [*-s*=__] [*--solr-home*=_DIR_] [*-u*=__] - [*-z*=__] __ __ +.... +bin/solr zk cp [-hrvV] [-s=] [--solr-home=DIR] [-u=] + [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc index bd5807a30351..a1d255cffdff 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-downconfig.adoc @@ -31,8 +31,10 @@ bin/solr zk downconfig - Download a configset from ZooKeeper to the local filesy // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk downconfig* [*-hvV*] *-d*=_DIR_ *-n*=__ [*-s*=__] - [*-u*=__] [*-z*=__] +.... +bin/solr zk downconfig [-hvV] -d=DIR -n= [-s=] + [-u=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc index 2c6a9cd1b7bb..32204d8a945c 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-ls.adoc @@ -31,7 +31,9 @@ bin/solr zk ls - List the contents of a ZooKeeper node. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk ls* [*-hrvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ +.... +bin/solr zk ls [-hrvV] [-s=] [-u=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc index ab820c5c254d..0e89af3899a6 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mkroot.adoc @@ -31,8 +31,10 @@ bin/solr zk mkroot - Make a znode in ZooKeeper with no data. Can be used to make // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk mkroot* [*-hvV*] [*--fail-on-exists*[=__]] [*-s*=__] - [*-u*=__] [*-z*=__] __ +.... +bin/solr zk mkroot [-hvV] [--fail-on-exists[=]] [-s=] + [-u=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc index 6df8366ad530..e7e75c5f2a46 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-mv.adoc @@ -31,8 +31,10 @@ bin/solr zk mv - Move (rename) a znode on ZooKeeper. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk mv* [*-hvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ - __ +.... +bin/solr zk mv [-hvV] [-s=] [-u=] [-z=] + +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc index 11d7bbbfca5c..4e72e4f0c405 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-rm.adoc @@ -31,7 +31,9 @@ bin/solr zk rm - Remove a znode from ZooKeeper. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk rm* [*-hrvV*] [*-s*=__] [*-u*=__] [*-z*=__] __ +.... +bin/solr zk rm [-hrvV] [-s=] [-u=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc index 49a44322da11..5abaadd5c7bc 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-upconfig.adoc @@ -31,8 +31,10 @@ bin/solr zk upconfig - Upload a configset from the local filesystem to ZooKeeper // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk upconfig* [*-hvV*] *-d*=_DIR_ *-n*=__ [*-s*=__] - [*-u*=__] [*-z*=__] +.... +bin/solr zk upconfig [-hvV] -d=DIR -n= [-s=] + [-u=] [-z=] +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc index 6d8e983c83a3..bc56603645d9 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk-updateacls.adoc @@ -31,8 +31,10 @@ bin/solr zk updateacls - Update ACLs for a ZooKeeper znode. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk updateacls* [*-hvV*] [*-s*=__] [*-u*=__] [*-z*=__] - __ +.... +bin/solr zk updateacls [-hvV] [-s=] [-u=] [-z=] + +.... // end::picocli-generated-man-section-synopsis[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc index 6b60a6c3827a..278b2782e93a 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc @@ -31,7 +31,9 @@ bin/solr zk - Sub commands for working with ZooKeeper. // tag::picocli-generated-man-section-synopsis[] == Synopsis -*bin/solr zk* [*-hV*] [COMMAND] +.... +bin/solr zk [-hV] [COMMAND] +.... // end::picocli-generated-man-section-synopsis[] From 6c827dfee593ebb60aea5d3344338ca7b4412ee4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20H=C3=B8ydahl?= Date: Thu, 9 Apr 2026 02:47:30 +0200 Subject: [PATCH 4/4] Fix xref links, while still using 'bin/solr' --- solr/solr-ref-guide/build.gradle | 4 ++++ .../deployment-guide/pages/cli/solr-zk.adoc | 16 ++++++++-------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index b06d28d25c79..24c176df4b17 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -605,6 +605,10 @@ String postProcessCliManPage(File rawFile, String asfHeader, String doNotEditNot /(?s)\/\/ tag::picocli-generated-man-section-header\[\].*?\/\/ end::picocli-generated-man-section-header\[\]\n\n?/, "= ${newTitle}\n:page-toclevels: 2\n\n") + // Fix xref paths: ManPageGenerator generates "xref:bin/solr-*.adoc" relative to the bin/ subdir, + // but in Antora xrefs are resolved from the module's pages/ root, so pages/cli/ files need "cli/" prefix. + content = content.replace('xref:bin/', 'xref:cli/') + // ManPageGenerator renders the command's qualified name as "bin/solr-start" (parent-dash-child). // Replace occurrences of that with the correct spaced form "bin/solr start". def picocliQualifiedName = 'bin/solr-' + baseName.substring('solr-'.length()) diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc index 278b2782e93a..85a7c659cd74 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-zk.adoc @@ -61,28 +61,28 @@ Sub commands for working with ZooKeeper. // tag::picocli-generated-man-section-commands[] == Commands -xref:bin/solr zk-downconfig.adoc[*downconfig*]:: +xref:cli/solr-zk-downconfig.adoc[*downconfig*]:: Download a configset from ZooKeeper to the local filesystem. -xref:bin/solr zk-upconfig.adoc[*upconfig*]:: +xref:cli/solr-zk-upconfig.adoc[*upconfig*]:: Upload a configset from the local filesystem to ZooKeeper. -xref:bin/solr zk-cp.adoc[*cp*]:: +xref:cli/solr-zk-cp.adoc[*cp*]:: Copy files or folders to/from ZooKeeper or ZooKeeper to ZooKeeper. -xref:bin/solr zk-ls.adoc[*ls*]:: +xref:cli/solr-zk-ls.adoc[*ls*]:: List the contents of a ZooKeeper node. -xref:bin/solr zk-mkroot.adoc[*mkroot*]:: +xref:cli/solr-zk-mkroot.adoc[*mkroot*]:: Make a znode in ZooKeeper with no data. Can be used to make a path of arbitrary depth but primarily intended to create a 'chroot'. -xref:bin/solr zk-mv.adoc[*mv*]:: +xref:cli/solr-zk-mv.adoc[*mv*]:: Move (rename) a znode on ZooKeeper. -xref:bin/solr zk-rm.adoc[*rm*]:: +xref:cli/solr-zk-rm.adoc[*rm*]:: Remove a znode from ZooKeeper. -xref:bin/solr zk-updateacls.adoc[*updateacls*]:: +xref:cli/solr-zk-updateacls.adoc[*updateacls*]:: Update ACLs for a ZooKeeper znode. // end::picocli-generated-man-section-commands[]