Updated docstrings for k-gain and non-linearity calibration

[hsergi]

Describe your changes

As part of the effort to review the doc in the calibration functions before moving to e2e simulations, I have updated docstrings for calibrate_kgain.py and calibrate_nonlin.py

Type of change

I have updated the main docstrings of calibrate_kgain.py and calibrate_nonlin.py describing what the data structure is in a common fashion for both calibration functions. The same information can be found on Confluence (link). It has been run thru Guillermo Gonzalez.

I also fixed a condition on the number of frames used to calibrate non-linearity in calibrate_nonlin.py

I have checked that e2e tests pass the same way as before the docstring changes.

Checklist before requesting a review

• [x ] I have verified that all unit tests pass in a clean environment and added new unit tests, as needed
• I have verified that all docstrings are properly formatted and added new documentation, as needed

[semaphoreP]

Should we wait until we have a discussion on new header formats before finalizing the updated docstring @hsergi?

[hsergi]

Sounds good. Marie asked me to work&submit this review that is compatible with v1.0. It clarifies a bit the structure of the cal data. We can wait, especially once we know how much work is required to update the use of the keywords.