Update docstrings to numpy style, add it to linting checks.

[bhazelton]

Description

Updated docstrings throughout. This builds on work started by @aelanman.

Also upgraded the RTD yaml to the newest version.

Motivation and Context

closes #230

Types of changes

• [x] Documentation change (documentation changes only)

Checklist:

For all pull requests:

• [x] I have read the contribution guide.
• [x] My code follows the code style of this project.

Documentation change checklist:

• [x] Any updated docstrings use the numpy docstring format.
• [x] If this is a significant change to the readme or other docs, I have checked that they are rendered properly on ReadTheDocs. (you may need help to get this branch to build on RTD, just ask!)

[codecov[bot]]

Codecov Report

Merging #379 (3d70c9e) into main (5cb2c6d) will increase coverage by 0.00%. The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main     #379   +/-   ##
=======================================
  Coverage   99.15%   99.15%           
=======================================
  Files          13       13           
  Lines        2001     2009    +8     
=======================================
+ Hits         1984     1992    +8     
  Misses         17       17           

Impacted Files	Coverage Δ
pyuvsim/astropy_interface.py	100.00% <ø> (ø)
pyuvsim/__init__.py	81.25% <100.00%> (+1.25%)	:arrow_up:
pyuvsim/analyticbeam.py	100.00% <100.00%> (ø)
pyuvsim/antenna.py	96.15% <100.00%> (+0.07%)	:arrow_up:
pyuvsim/baseline.py	90.90% <100.00%> (+0.43%)	:arrow_up:
pyuvsim/mpi.py	100.00% <100.00%> (ø)
pyuvsim/profiling.py	97.72% <100.00%> (ø)
pyuvsim/simsetup.py	99.88% <100.00%> (+<0.01%)	:arrow_up:
pyuvsim/telescope.py	100.00% <100.00%> (ø)
pyuvsim/utils.py	98.11% <100.00%> (+0.01%)	:arrow_up:
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 5cb2c6d...3d70c9e. Read the comment docs.

[bhazelton]

Thanks for the detailed review on this @steven-murray! I think I addressed all your comments. I also fixed the docs for files in the scripts, benchmarking and reference_simulation folders and fixed some warning handling that was making the tests fail. Are you willing to take another look?

[steven-murray]

Thanks @bhazelton, yup, will take another look soon

[steven-murray]

From looking at the diff, everything looks good. I'm just having a quick peruse of the compiled docs on rtd, and here are some comments:

• The main page has a list of requirements that aren't formatted well (also under Outputs)
• Bad formatting under "Testing":
• There's something weird about how "Generating config files from data" and "parallelization" are in the side bar, but should be sub-listed under "Running a simulation"
• Missing backticks, and missing autoref here:
• Weird formatting:
• More weird formatting:
• Formatting on "Gaussian":
• Formatting for parameters:
• Would be better if possible arrangements could be in list format:
• Again with the list format:
• Weird formatting from reuse_spline on:
• (Ah, I just realized I think the above are auto-listed attributes. Maybe better to have a heading before starting to list them?)
• I assume "Sets" is not a valid section:

I think that's it!

[bhazelton]

@steven-murray Thank for the careful read through the RTD rendered docs!! The biggest problem was that the RTD theme had broken all instances of bulleted lists (this happened before on pyuvdata but the fix I used there no longer works -- this is a new problem, see https://github.com/readthedocs/sphinx_rtd_theme/issues/1236)

I think I fixed all the things you raised except that I cannot seem to alter the behavior for how attributes are listed. They are in the docstring with a heading, but that heading is removed automagically by Sphinx. The appearance is a little better in some non-RTD themes in terms of differentiating them from parameters, but even in those themes they do not have the Attributes heading. If you have suggestions on this front I'd be happy to hear them!

[bhazelton]

@steven-murray I figured out how to make the Attributes section look like the Parameters section. Do you like this better than what we had before?

[bhazelton]

I just realized that we're using an old version of the RTD yaml on this repo. I'm going to update to the newer version in this PR as well.

[bhazelton]

@steven-murray ok, I think I've got everything working properly now if you want to take another look.

[bhazelton]

Yes, the fix for the bullets is to pin the theme to exactly 0.5.2. Older builds from that had one cause for the bullets to fail and the newer builds have a different cause for the bullets to fail 😂