epugh commented on code in PR #4271:
URL: https://github.com/apache/solr/pull/4271#discussion_r3248090607
##########
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
Review Comment:
So, it's funny what things we check into source code that are generated and
what are not (SolrJ endpoints from OpenAPI annotations for example). I just
ran the task to generate the cli pages and it went super fast.. What value
are we getting by checking them into source code? I don't have a super strong
opinon one way or the other, more of an observation.
##########
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`::
Review Comment:
awesome! I was jsut thinking about this.
##########
dev-docs/ref-guide/antora.adoc:
##########
@@ -61,6 +61,38 @@ Instead, update `antora.template.yaml`, and `gradlew
buildLocalSite` will build
The only reason you will likely need to change the `antora.template.yml` is if
you are introducing new variables for dependency versions.
+== Auto-generated CLI Reference Pages
+
+The `bin/solr` command-line tool documentation is partially auto-generated
from the picocli `@Command`, `@Option`, and `@Parameters` annotations in the
Java source.
+
+=== How it works
+
+For each command registered in `org.apache.solr.cli.SolrCLI` that uses picocli
annotations, a dedicated AsciiDoc page is generated by
`picocli.codegen.docgen.manpage.ManPageGenerator` and committed to:
+
+----
+solr/solr-ref-guide/modules/deployment-guide/pages/cli/
+----
+
+The generated pages are post-processed to be Antora-compatible (correct page
title, `:page-toclevels:` attribute, ASF license header, DO NOT EDIT notice).
+The navigation section in `deployment-nav.adoc` between the `//
CLI-DOCS-START` and `// CLI-DOCS-END` markers is also updated automatically.
+
+The main landing page `solr-control-script-reference.adoc` provides an
overview of the available tools with links to each man-page.
+
+=== Gradle targets
+
+`./gradlew :solr:solr-ref-guide:generateCliDocs`::
+Regenerates all pages under `pages/cli/` from the current picocli annotations
and updates the nav.
+Run this after modifying any `@Command`, `@Option`, or `@Parameters`
annotation in `solr/core/src/java/org/apache/solr/cli/`.
+
+`./gradlew :solr:solr-ref-guide:checkCliDocsUpToDate`::
+Verifies that the committed pages in `pages/cli/` are in sync with the current
annotations.
+This target is wired into `gradlew check`, so CI will catch annotation changes
that were not followed by a `generateCliDocs` run.
+
+=== Adding docs for a new tool
+
+The new command will automatically appear in the generated pages and the
navigation when running `gradlew generateCliDocs`.
+You will need to tie it in to the `solr-control-script-reference.adoc`
yourself.
Review Comment:
Hopefully we rework `solr-control-script-reference.adoc`.... I see the
table you added flagging which have autogenerated links. At a minimum, we
should eliminate the listing of parameters to each command that exist in
`solr-control-script-reference.adoc` and lean into using the generated docs.
I don't know if that is part of this PR or it's own?
##########
solr/core/src/java/org/apache/solr/cli/CreateTool.java:
##########
@@ -47,7 +47,23 @@
name = "create",
mixinStandardHelpOptions = true,
description =
- "Creates a core or collection depending on whether Solr is running in
standalone (core) or SolrCloud mode (collection).")
+ "Creates a core or collection depending on whether Solr is running in
standalone (core) or SolrCloud mode (collection).",
+ exitCodeListHeading = "%nExit Codes:%n",
+ exitCodeList = {
+ "0:Collection or core created successfully.",
+ "1:Failed to create; Solr may not be running, or the collection/core
already exists."
+ },
+ footerHeading = "%nExamples:%n",
+ footer = {
+ " # Create a collection in SolrCloud mode",
Review Comment:
i wonder..... Should we introduce a `bin/solr core create -c myCore` and
keep `bin/solr create -c myCollection` as solr cloud? are there use cases
where folks want to work with a specific core while in solr cloud mode? This
is a bit off topic.
##########
solr/core/src/java/org/apache/solr/cli/DeleteTool.java:
##########
@@ -42,7 +42,20 @@
name = "delete",
mixinStandardHelpOptions = true,
description =
- "Deletes a collection or core depending on whether Solr is running in
SolrCloud or standalone mode.")
+ "Deletes a collection or core depending on whether Solr is running in
SolrCloud or standalone mode.",
+ exitCodeListHeading = "%nExit Codes:%n",
+ exitCodeList = {
+ "0:Collection or core deleted successfully.",
+ "1:Failed to delete; collection or core may not exist, or Solr may not
be running."
Review Comment:
wow... actual documentation of return codes! Helpful for folks writing
automation.
##########
solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc:
##########
@@ -17,7 +17,24 @@
.Deployment Guide
+// CLI-DOCS-START
* xref:solr-control-script-reference.adoc[]
+** xref:cli/solr-create.adoc[create]
+** xref:cli/solr-delete.adoc[delete]
+** 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]
Review Comment:
this is nice nesting!
##########
solr/core/src/java/org/apache/solr/cli/CreateTool.java:
##########
@@ -47,7 +47,23 @@
name = "create",
mixinStandardHelpOptions = true,
description =
- "Creates a core or collection depending on whether Solr is running in
standalone (core) or SolrCloud mode (collection).")
+ "Creates a core or collection depending on whether Solr is running in
standalone (core) or SolrCloud mode (collection).",
+ exitCodeListHeading = "%nExit Codes:%n",
+ exitCodeList = {
+ "0:Collection or core created successfully.",
+ "1:Failed to create; Solr may not be running, or the collection/core
already exists."
+ },
+ footerHeading = "%nExamples:%n",
+ footer = {
+ " # Create a collection in SolrCloud mode",
Review Comment:
do we still need to litter ` in SolrCloud mode` everywhere? Or... `Create
a collection in SolrCloud mode and a core in User Managed mode`? (sigh)...
##########
solr/solr-ref-guide/modules/deployment-guide/pages/solr-control-script-reference.adoc:
##########
@@ -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
Review Comment:
I think all of this can be removed since we have `solr-start.adoc`!
##########
solr/core/src/java/org/apache/solr/cli/StartCommand.java:
##########
@@ -19,7 +19,20 @@
import java.util.concurrent.Callable;
import picocli.CommandLine;
[email protected](name = "start", description = "Starts Solr in standalone
or SolrCloud mode.")
[email protected](
+ name = "start",
+ description = "Starts Solr in standalone or SolrCloud mode.",
Review Comment:
standalone --> user-managed ? the switch is --user-managed. I dislike the
term user managed, but it is what we agreed...... "Disagree and commit' ;-)
##########
solr/solr-ref-guide/build.gradle:
##########
@@ -540,6 +545,225 @@ task buildOfficialSite(type: NpxTask) {
}
}
+/*
+ CLI Documentation Generation from Picocli Annotations
Review Comment:
it's a shame that this kind of thing isn't built into Antora and we have to
write so much code. On the other hand, it's nicely commented and pretty
readable unlike some other Gradle stuff I've seen!
--
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]
