SOLR-17697 Ref-guide documentation for new picocli commands

[janhoy]

This is a WIP POC for auto generating CLI ref-guide docs for the new picoCli instrumented tools. The docs are auto generated using PicoCLI's ManPageGenerator, one ref-guide page per tool. Menus are also updated, and tools are cross-linked. The existing landig page "Solr Control Script Reference" is reduced from a huge all-in-one page to an overview page that introduces the CLI and links to the generated man-pages. This way, our docs will always stay in sync with the actual @picocli annotations in the code.

There are two gradle tasks added in this PR:

• generateCliDocs - Regenerate CLI reference pages in pages/cli/ from picocli annotations.
• checkCliDocsUpToDate - Verify that pages/cli/ CLI docs are in sync with picocli annotations - runs on check

Screenshot:

This is a draft, mostly AI generated, not reviewed in full. Need discussion about how we want the docs to be.

https://issues.apache.org/jira/browse/SOLR-17697

[janhoy]

Unfortunately these links will not work as the tool-name bin/solr contains a slash. I propose we change the tool name to simply solr (it is obvious that it is in the bin folder), which will fix this.

Only reason I flipped it to bin/solr is that the BATS tests currently assert for that string in outputs, and we want the BATS tests to run green on both commons-cli and picocli parsers. WDYT?

[epugh]

I think that if we are moving to picocli, then it's okay that the bats tests only work with picocli. I think that while it's "cool" that we have support for both, it's also really tough because of situations just like this one. I think it's more important that .bats tests support only picocli and that everything else work nicely in the picocli centric world.

[janhoy]

Yes, we could flip BATS tests to picocli only and adjust some assert texts. The most important is to make sure that picocli has exactly the same option behavior as before, so we can switch in a minor version without compat break.

But so far I have been optimistic to try to get them green for both old and new. Can clip from usage: bin/solr foo to regex usage: (bin/)?solr foo of course...

[epugh]

Love it! That also doesn't seem to hard to read/maintain.

[janhoy]

We could obviously add @picocli annotations to document exit status for all tools asl well... Not sure how useful it is. Guess for the assert tool it would be useful, and for the stop tool to signal success...

[janhoy]

This section is temporary, not intended for release. I suppose this entire "landing page" needs to be re-written in a way that gives a good overview, without touching the details.

Question: Currently we have usage examples hand written in the ref-guide page. We could instead add usage examples for each tool either in the description field or footer field, or some custom annotation that we invent and tie in when generating docs:

@Command(
    name = "myapp",
    footerHeading = "%nExamples:%n",
    footer = {
        "  # Basic usage",
        "  myapp --input foo.txt",
        "",
        "  # With options",
        "  myapp --input foo.txt --verbose"
    }
)

I think perhaps using footer for this purpose is a good approach, this way also the --help for each tool will print usage examples. I think we can sacrifice the current refguide URL link we have in all the footers. It can perhaps be included on the main bin/solr command only.

[epugh]

I like that idea. And the ref guide link is a bit of an oddity too anyway...

[epugh]

We have been caught many times with ref guide differences from reality in the docs.

[janhoy]

Fix this - use name="solr" and remove this hack

[dsmiley]

This way, our docs will always stay in sync with the actual @picocli annotations in the code.

Nice!

[epugh]

I want to say how much i like the zk nesting of sub commands. I started hacking on a configset command in our old framework, and it was a bummer how hard it was to do nested subcommands. I can imaginge bin/solr configset upload -blah -blah and bin/solr configset putfile -blah -lbah and that nesting nicely in the docs with picocli!