CLI options are not documented

[sebbASF]

• [x] I have searched the issues (including closed ones) and believe that this is not a duplicate.

Issue

I could not find any documentation of the CLI options such as --fatal etc.

Once Pelican is installed, of course one can use the help option, but that does not provide sufficient information for some of the options, and is not really a substitute for documentation.

[justinmayer]

One way to document the CLI commands and options without getting out-of-sync could be to dynamically generate this documentation from the output of pelican --help.

In terms of implementing that, is this something you would like to help out with?

[sebbASF]

The current output from help would need augmenting, as it does not give full details of all the options. For example it would be useful to document how to override PLUGIN_PATHS which is a list (array). There are various other options which could do with more explanation.

Doing so in the option list would make the help rather unwieldy. The format is also not that easy to read; it's best kept as a reminder rather than full documentation.

A possible work-round is to document the settings in the code itself, e.g. as documentation for the parse_arguments function. The main documentation could then just link to the documentation block.

[justinmayer]

I think your proposed workaround could indeed be a good place to start. 👍

[kdeldycke]

Or you could depends on sphinx-click and have the CLI documentation autogenerated by the way of the .. click:: rST directives.

See for instance the results of my CLI in its Sphinx documentation: https://kdeldycke.github.io/meta-package-manager/cli-parameters.html