Add CLI options table

[Jessie212]

Description

Is this change a fix, improvement, new feature, refactoring, or other?

Improvement

Is this a change to the core query engine, a connector, client library, or the SPI interfaces? (be specific)

Documentation only

How would you describe this change to a non-technical end user or system administrator?

Add CLI options table

Related issues, pull requests, and links

Documentation

( ) No documentation is needed.
(x) Sufficient documentation is included in this PR.
( ) Documentation PR is available with #prnumber.
( ) Documentation issue #issuenumber is filed, and can be handled later.

Release notes

(x) No release notes entries required.
( ) Release notes entries required with the following suggested text:

# Section
* Fix some things. ({issue}`issuenumber`)

[electrum]

I don't think this is particularly useful. Anyone running the CLI can use --help to see the exact options for the current version they are using. Copying a snapshot of the help output into a table means that it will become outdated.

[mosabua]

This is only the draft .. we will make it useful with links from the content to the table and vice versa .. and we will get rid of partial copies of that data in the LDAP and Kerberos page .. stay tuned @electrum

And yes.. of course we will have to maintain it and add new options as they come up.

[mosabua]

A whole bunch of things we should do in this PR.. and maybe a few bigger ones to do separately later. Do all the easy ones and then lets sync up and maybe decide on getting to merge and follow up PRs

[mosabua]

@electrum we rejigged it to be multiple tables in the desired context. Please have a look and confirm that is what you are looking for. Then we can proceed with final polish.

[hashhar]

Some configs don't serve any purpose being documented here since the CLI help output includes exact same text already.

For things that need elaboration like how to use Kerberos auth and Password auth etc. I think it would be more useful to have them as "guides".

I'll take another look regarding accuracy.

I'd suggest to remove the table for now, and focus on Kerberos, Password/LDAP auth in this PR. Depending on how this evolves we can iterate.

[mosabua]

@hashhar and @electrum at this stage we just want to confirm that this is the right approach now. I realize some options are just the output of the help command. This is only temporary as we plan to expand the docs more iteratively .. ideally we could get this merged and then update more in a follow up PR .. but at a minimum we need to know if this approach is good to be expanded upon one way or another,

[hashhar]

The documentation seems good to me but the things we are documenting I'm unsure about.

IMO for configs which are just toggles or have well defined values we should omit them. they just bury the other useful information.

I would prefer if we had a section for "Authentication" with subsections for password auth (password file/ldap/salesforce - all of these are password auth), JWT auth, OAuth (external authentication), Kerberos.

Then a section for "Security" (or "TLS/SSL"?) with the keystore, truststore, insecure options.

Then some for "Output" with the various output formats and how they look like.

And so on...

The table or trying to enumerate all options seems like a bad idea to me because it's just noise and tends to bury useful things in the noise.

Personally I feel "Authentication" + "SSL" related configs should be documented in detail to start. And then we can move on to others.

[mosabua]

What you are suggesting is exactly what is in this PR @hashhar .. so I am not sure I understand. Lets try to sync up for a meeting early next week.

[hashhar]

LGTM % comments.

I hope this is more clear about what I mean.

[hashhar]

I like this much better. Thanks for refining this.

Some nits.

[hashhar]

Very nice. LGTM % comments.

[mosabua]

This is a great step forward. Lets merge this to unblock other PRs and follow up work @hashhar @electrum

[hashhar]

Awesome contribution @Jessie212.

Thanks for being patient with the long review.

@electrum Can you remove "request changes" in case your concerns are addressed? This doesn't document simply a list of configs now - it actually explains the important ones and mentions things like possible values and how they may be used.

Outdated