search

dandi / dandi-cli

DANDI command line client to facilitate common operations
https://dandi.readthedocs.io/
Apache License 2.0
21 stars 25 forks source link

Automate CLI docs in our sphinx docs to avoid manual and duplicate specification #1002

Open yarikoptic opened 2 years ago

yarikoptic commented 2 years ago

ATM manually curated, duplicating work/docs in click specifications and under docs/.

Initial attempt to automate was via sphinx-click in https://github.com/dandi/dandi-cli/pull/831 but there were shortcomings at that point.

@satra also suggested https://github.com/jdidion/autoclick in https://github.com/dandi/dandi-cli/pull/1001#discussion_r865961200 so (I guess) docstrings (not really CLI --options etc) are displayed as is, and then CLI interfaces are produced. Not sure if that is not "too ad-hoc/heavy".

So may be sphinx-click should be reconsidered or some other approach developed.

jwodder commented 2 years ago

@yarikoptic I'd like to reiterate my point from #831:

--help output is meant to be concise, while online documentation is meant to be thorough. These two requirements are [...] at odds

If your goal is for the Sphinx docs to display the same information as the --help output, I believe that is the wrong thing to do.

yarikoptic commented 2 years ago

well, I guess I have been spoiled by git and datalad (which adopted git's model) that --help is pretty much a manpage with thorough description. There is a "concise" SUMMARY which it starts with, includes the full signature (not just [OPTIONS]) and user then is given a choice for details to be provided below. That avoids the need for looking up extra information online for that command.

If it is really desired to have different help, it is easy to workaround the fact that sphinx-click does not allow two. We can have a helper click_help(short, long) so it is like help=click_help(None, "Provided long description only in sphinx") or alike, and inside click_help decides between the two based e.g. on DANDI_DOC_LONG_HELP env var which it sets while building docs. But, again, I do not really see why --help should be crippled.

Another way for concise/long is -h vs --help we support in datalad:

$> datalad clone -h
Usage: datalad clone [-h] [-d DATASET] [-D DESCRIPTION] [--reckless [auto|ephemeral|shared-...]] [--version] SOURCE [PATH] ...

Use '--help' to get more comprehensive information.

$> datalad clone --help | head
Usage: datalad clone [-h] [-d DATASET] [-D DESCRIPTION]
                     [--reckless [auto|ephemeral|shared-...]] [--version]
                     SOURCE [PATH] ...

Obtain a dataset (copy) from a URL or local directory

The purpose of this command is to obtain a new clone (copy) of a dataset
and place it into a not-yet-existing or empty directory. As such CLONE
...

but frankly I rarely if ever use -h