docs: Demonstrate CLI API over running module as script

[matthewfeickert]

• As installation creates the executables 'bin/scikit-hep-testdata' and 'bin/skhep-testdata', demonstrate these in the README rather than running the module as a script with '-m'.
  • c.f. https://docs.python.org/3/using/cmdline.html#cmdoption-m

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.51%. Comparing base (df3dbc8) to head (d9005a6).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #195   +/-   ##
=======================================
  Coverage   72.51%   72.51%           
=======================================
  Files           4        4           
  Lines         131      131           
=======================================
  Hits           95       95           
  Misses         36       36           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[matthewfeickert]

cc @henryiii for review as he was the last to touch this segment of the README and added the CLI options in PR #51.

[APN-Pucky]

Suggested change

	```
	```bash

[matthewfeickert]

Bash syntax highlighting on GitHub looks the same as no syntax highlighting on GitHub if you aren't using explicit Bash commands. I would normally suggest console, as that's more correct as people will be executing these in shells regardless of shell type, but that does change the syntax highlighting in a way that just converts all of it to a new color, which isn't very useful.

Is there an advantage to selecting bash here? If no, should we change Scikit-HEP style recommendations?

[ariostas]

I guess none of the three options are much better than the others.

skhep-testdata --all --dir local

skhep-testdata --all --dir local

skhep-testdata --all --dir local

But to be consistent with the rest of the readme, it would be good to keep using bash or switch everything else to either of the other options.

[APN-Pucky]

Besides consistency, it also adds context for LLMs even if it does not change visually on Github. I don't think sh vs bash vs console matters, except that bash seems more common. Maybe all should be changed to console then?

[matthewfeickert]

Nothing:

skhep-testdata --all --dir local

bash:

skhep-testdata --all --dir local

console:

skhep-testdata --all --dir local

@ariostas @APN-Pucky I think that this demonstrates why trying to apply a blanket default to every code block is not a reasonable approach. bash means Bash code. A tool CLI is not Bash, and so the local is "correctly" incorrectly highlighted, as local is valid Bash keyword. console is a different color and looks strange because it is expecting to display a command at the prompt and the output, as can be seen in this example

$ skhep-testdata --all --help
usage: skhep_testdata [-h] [--all] [--list] [--dir DIR] [file_path ...]

Expand a testing dataset path to a full path, downloading things if a remote file is request.

positional arguments:
  file_path             Path to expand

options:
  -h, --help            show this help message and exit
  --all                 Download all files
  --list                List all files
  --dir DIR             Path to store in (DEFAULT: ~/.local/skhepdata)

Besides consistency, it also adds context for LLMs even if it does not change visually on Github

I do not find this to be a good argument. We should not be changing how we write human documentation for LLMs — that seems the wrong way round in terms of adaptation. It is reasonable to write different forms of docs if you want to cater to LLMs, but it would also provide incorrect context to label things as bash or console when they're not.

But to be consistent with the rest of the readme, it would be good to keep using bash or switch everything else to either of the other options.

I'd prefer to move to removing syntax hints that do not correspond to the actual language in the block. Though if others would prefer other options I'd suggest moving this to a GitHub Issue for additional discussion and following up on the mailing list for GitHub org wide agreement.

[APN-Pucky]

Suggested change

	```
	```bash

[APN-Pucky]

Suggested change

	```
	```bash

[eduardo-rodrigues]

The changes seem good to me.

[ariostas]

The changes also look good to me. I left a comment in the above discussion, but it's a minor thing, so I'll approve it already.

[matthewfeickert]

Sorry for being slow here. As @APN-Pucky and @ariostas gave 👍 to #195 (comment) I'm going to merege this. If people would like to have additional discussion on Markdown that's great by me, but please open a new issue and let's follow up there. 👍