Quickstart Guide Example File Clarity

[ekschuman]

Review: openjournals/joss-reviews#2123

I worked through the quickstart guide on the official documentation. I had some difficulty with using the provided example files to follow the quickstart guide. For me getting started in the documentation, it wasn't obvious which file belonged to which category when getting to the generate_categorize function (lidar, radar, model, mwr). Explicitly mentioning the provided example files in the code examples would probably be a smoother learning experience for new users.

For the steps where mira2nc and ceilo2nc are called, it seemed a bit confusing that the functions are named x2nc, but the provided example files are already in the netCDF4 format, with the nc extension. I was looking for example files with extensions similar to the example code snippets, but I didn't find any. I then assumed that the .nc files were the already-processed versions, and then tried to use them in generate_categorize directly. I eventually found that you had to use mira2nc and ceilo2nc on the provided .nc files first, then use the outputs in generate_categorize.

Additionally, in the quickstart documentation, it could be helpful to clarify that all 4 files are necessary for generate_categorize.

[tukiains]

It is indeed confusing if the quickstart examples use different file names than there are in the provided example input files. It is now fixed, see https://github.com/actris-cloudnet/cloudnetpy/commit/56b02c359069dc507a0cbe82d8a05c3a7296f188. It should be much clearer now because one can just download the input files and copy-paste all the example function calls in order without changing anything.

I can also understand that the function names ceilo2nc etc. can be confusing if the input file is already a .nc file. The names try to indicate that, in principle, the input can be any format while the output is always netCDF. I added a few sentences in the API documentation to explain this better (see https://github.com/actris-cloudnet/cloudnetpy/commit/eb7ce3e3350189b7055ffa12e76145ea2bf919d2). If this is still not clear enough we have to think about changing all the function names later when we have the next major API update.