Documenting config files

[julienguy]

The command picca_delta_extraction.py --help should dump a comprehensive configuration file with all possible options commented out (and with explanations). Currently we have:

picca_delta_extraction.py --help

usage: picca_delta_extraction.py [-h] config_file

Compute the delta field from a list of spectra

positional arguments:
  config_file  Configuration file

optional arguments:
  -h, --help   show this help message and exit

[iprafols]

Hi @julienguy, all the possible configuration options are documented in the configuration tutorial, I will add a sentence here pointing to that file. Let me know if you think this solves the issue.

[Waelthus]

I agree with Julien that would be a good thing to have. The updated help is already useful, but having an option creating an commented default config file with all options would be even better, but that might take some time to code up.

[iprafols]

Hi @julienguy , continuing the discussion from the PR on the issue

I don't think it's a good solution to point to a notebook. Do we really need a web browser with a ipython notebook interpreter to run picca?

We don't need the notebook to run picca. The notebook is just a tutorial that explains how to build a configuration file from scratch and details all the available options. There are also some configuration examples in $PICCA/examples/delta_extraction. We could point also to those examples. Do you think this would be enough?

Another option would be to export the notebook as a pdf or an HTML file so that it is more accessible (without the need for jupyter notebook to be installed).

However, I don't think it is a good idea to give a thorough description of all the configuration options with the help of the code. There are too many of them (and will possibly evolve). This means that we would need to maintain two separate versions of the configuration options. If we do this at some point it is likely that both pieces of documentation will be incomplete/incorrect.

Or do you have an alternative way to fix this issue?

[Waelthus]

I don't think rendering to html would be that useful, also jupyter does not need to be installed if web-access is available given that github renders the notebook just fine. Updating the examples with all reasonable options etc might be a useful thing to do (and pointing to their existance in the --help)

I guess that ideally we'd want to have a proper read-the-docs-style site generated through sphinx (i.e. compiling all the docstrings and adding additional text). And we'd want to have all config options (except for maybe debug-only options) documented there, updated with code changes in a (semi-)automatic way (at least on release). This would make the jupyter notebooks unnessessary, increase self-documentation of the code (as most of the help is rendered from the docstrings), and give us a proper page to point people too. However, this will be some amount of work to get going.

For the meantime I think the current state is ok.