janhoy commented on code in PR #4739: URL: https://github.com/apache/solr/pull/4739#discussion_r3835750602
########## solr/solr-ref-guide/modules/deployment-guide/pages/cli/solr-package.adoc: ########## @@ -0,0 +1,130 @@ +// 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 package +:page-toclevels: 2 + +// tag::picocli-generated-man-section-name[] +== Name + +bin/solr package - Install, deploy and manage Solr packages in SolrCloud. + +// end::picocli-generated-man-section-name[] + +// tag::picocli-generated-man-section-synopsis[] +== Synopsis + +.... +bin/solr package [-vy] [--cluster] [--update] [-c=COLLECTION] + [--collections=COLLECTIONS] [-u=<credentials>] [--param=PARAMS]... + [-s=<solrConnection> | --solr-url=<solrUrl> | -z=<zkHost>] COMMAND + [ARGS...] +.... + +// end::picocli-generated-man-section-synopsis[] + +// tag::picocli-generated-man-section-description[] +== Description + +Install, deploy and manage Solr packages in SolrCloud. + +// end::picocli-generated-man-section-description[] + +// tag::picocli-generated-man-section-options[] +== Options + +*-c*, *--collection*=_COLLECTION_:: + The collection to apply the package to. + +*--cluster*:: + Specifies that this action should affect cluster-level plugins only. + +*--collections*=_COLLECTIONS_:: + Specifies that this action should affect plugins for the given collections only, excluding cluster level plugins. + +*--param*=_PARAMS_:: + List of parameters to be used with the deploy command. + +*-s*, *--solr-connection*=_<solrConnection>_:: + Zookeeper or HTTP(s) connection string; unnecessary if SOLR_CONNECTION is defined in solr.in.sh; otherwise, defaults to localhost:9983. + +*--solr-url*=_<solrUrl>_:: + Base Solr URL, which can be used to determine the zk-host if that's not known. + +*-u*, *--credentials*=_<credentials>_:: + Credentials in the format username:password. Example: --credentials solr:SolrRocks + +*--update*:: + If a deployment is an update over a previous deployment. + +*-v*, *--verbose*:: + Enable verbose mode. + +*-y*, *--no-prompt*:: + Don't prompt for input; accept all default choices, defaults to false. + +*-z*, *--zk-host*=_<zkHost>_:: + 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 + +_COMMAND_:: + Package command: add-repo, add-key, list-installed, list-available, list-deployed, install, deploy, undeploy, uninstall. + +[_ARGS_...]:: + Command-specific arguments (package name[:version], repository name/URL, key file, etc.). + +// 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[] +== Exit Codes: + +*0*:: + Operation completed successfully. + +*1*:: + Operation failed; check output for details. + +// end::picocli-generated-man-section-exit-status[] + +// tag::picocli-generated-man-section-footer[] +== Examples: + +[%hardbreaks] + # Add a package repository + bin/solr package add-repo myrepo https://my.repo.example/bin/solr packages Review Comment: Good catch, and the root cause is in the doc generator rather than here: postProcessCliManPage in solr/solr-ref-guide/build.gradle (~line 698) does `content.replaceAll("${baseName}(?!-)", newTitle)`, and the `(?!-)` lookahead doesn't prevent solr-package from matching inside solr-packages. package is the first migrated command whose name is a prefix of a plausible word, so this will bite future tools too. Two separate fixes: 1. In this PR: change the example URL in the `@Command(footer = ...)` to something that doesn't embed the command stem (e.g. https://my.repo.example/repo) and re-run `./gradlew :solr:solr-ref-guide:generateCliDocs`. 2. Follow-up on the feature branch: tighten the regex to a real word boundary `((?![-\w]) rather than (?!-))`, since that change affects every generated CLI page. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
