Documentation - developer and helper functionality documentation for xtdb-cli tool

[stephanie0x00]

Changes

This PR adds :

• the help texts to the XTDB cli tool for all commands and optional arguments and a general description for the tool itself. Most of the CLI tool texts were copied and adjusted where necessary based on the XTDB HTTP documentation (https://v1-docs.xtdb.com/clients/1.24.3/http/)

• the documentation on how to use the xtdb-cli tool to https://docs.openkat.nl/. It includes a notification that OpenKAT doesn't use vanilla xtdb and provides some examples on how to use the xtdb-cli tool.

Issue link

This PR closes: #2877

Demo

$ ./xtdb-cli.py --help
Usage: xtdb-cli.py [OPTIONS] COMMAND [ARGS]...

  This help functionality explains how to query XTDB using the xtdb-cli tool. The help functionality for all default
  XTDB commands was copied from the official XTDB docs for the HTTP implementation. Not all optional parameters as
  available on the HTTP docs may be implemented.

Options:
  -n, --node TEXT        XTDB node  [default: 0]
  -u, --url TEXT         XTDB server base url  [default: http://localhost:3000]
  -t, --timeout INTEGER  XTDB request timeout (in ms)  [default: 5000]
  -v, --verbosity        Increase the verbosity level  [default: 0]
  -h, --help             Show this message and exit.

Commands:
  active-queries       Returns a list of currently running queries.
  attribute-stats      Returns frequencies of indexed attributes
  await-tx             Waits until the node has indexed a transaction that is at or past the supplied tx-id.
  await-tx-time        Blocks until the node has indexed a transaction that is past the supplied tx-time.
  entity               Returns the document map for a particular entity.
  entity-tx            Returns the transaction details for an entity - returns a map containing the tx-id and...
  history              Returns the history of a particular entity.
  latest-completed-tx  Returns the latest transaction to have been indexed by this node.
  latest-submitted-tx  Returns the latest transaction to have been submitted to this cluster.
  list-keys            List all keys in node
  list-values          List all values in node
  query                EDN Query (default: "{:query {:find [ ?var ] :where [[?var :xt/id ]]}}")
  recent-queries       Returns a list of recently completed/failed queries.
  slowest-queries      Returns a list of slowest completed/failed queries ran on the node.
  status               Returns the current status information of the node
  submit-tx            Takes a vector of transactions (any combination of put, delete, match, evict and fn) and...
  sync                 Wait until the consumer’s lag is back to 0 (i.e.
  tx-committed         Checks if a submitted tx was successfully committed, returning a map with tx-committed and...
  tx-log               Returns a list of all transactions, from oldest to newest transaction time - optionally...
  txs                  Show all document transactions

And now also with the helper text for the optional arguments:

$ ./xtdb-cli.py history --help
Usage: xtdb-cli.py history [OPTIONS] KEY

  Returns the history of a particular entity.

Options:
  --with-docs         Includes the documents in the response sequence, under the doc key (boolean, default: false)
  --with-corrections  Includes bitemporal corrections in the response, inline, sorted by valid-time then tx-id
                      (boolean, default: false)
  -h, --help          Show this message and exit.

Code Checklist

• All the commits in this PR are properly PGP-signed and verified.
• This PR only contains functionality relevant to the issue; tickets have been created for newly discovered issues.
• I have written unit tests for the changes or fixes I made.
• For any non-trivial functionality, I have added integration and/or end-to-end tests.
• I have performed a self-review of my code and refactored it to the best of my abilities.

Communication

• I have informed others of any required .env changes files if required and changed the .env-dist accordingly.
• I have made corresponding changes to the documentation, if necessary.
• I have included comments in the code to elaborate on what is not self-evident from the code itself, including references to issues and discussions online, or implicit behavior of an interface.

---

Checklist for code reviewers:

Copy-paste the checklist from the docs/source/templates folder into your comment.

---

Checklist for QA:

Copy-paste the checklist from the docs/source/templates folder into your comment.

[ammar92]

Just a few minor suggestions, but should be ready to merge soon?

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud