Open yarikoptic opened 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.
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
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.