MMIF CLI script documentation

[marcverhagen]

Documentation for CLI scripts is accessed in three ways:

1. Using mmif --help.
2. Using mmif subcommand --help.
3. Online at https://clams.ai/mmif-python/1.2.1/cli.html.

The code for the scripts has a method describe_argparser() that generates a short and a long description, the short one is used for 1 and the long one for 2 and 3. Sometimes the code generates regular text for the long description (for mmif describe) and sometimes it generates restructured text (for all others).

The issue I see is that long regular text would be appropriate for 2 and restructured text (or markdown) for 3. At the moment, both 2 and 3 display raw text, whether it is restructured or not. For 3 the help is generated automatically using the long description from describe_argparser(), but it is printed in raw form. For 2 we sometimes get raw restructured text, which is hard to read.

I propose to work towards using three help strings:

1. A short description for mmif --help.
2. A long description for mmif subcommand --help.
3. A long description in restructured text displayed properly at https://clams.ai/mmif-python/1.2.1/cli.html.

Personally I can do without 3. It would then be better to change the long string for mmif describe into regular text, but it would probably be less work.

[marcverhagen]

Hmmmm, it is a bit more complicated than what I wrote above so I may have to rethink that.

[marcverhagen]

What I did not notice was that the long string is used as the description for the argparser help, coming between the synopsis (something like "usage: mmif describe [-h] [-o OUTPUT] [-p] [MMIF_FILE]") and the options. So if you add a lot of restructured text in there the results are somewhat atypical.

[marcverhagen]

And I do not know how I did not see this for the last few hours, but on https://clams.ai/mmif-python/1.2.1/cli.html the main command is described as

usage: sphinx-build [-h] [-v] {} ...

options:
  -h, --help     show this help message and exit
  -v, --version  show program's version number and exit

sub-command:
  {}

This is because the documentation is created while running sphinxs-build. You can use the prog parameter to overrule the name, but I do not know why the subcommands aren't in there. The best I could think of is to have a special argparser method that does not add subcommands.

NOTE: this was recently fixed.