Update docstrings to numpydoc format

[dhomeier]

Description

This is beginning to address #466; I have tried to clarify or extend the docs where they seemed ambiguous or incomplete, but someone more familiar with the functionality should review the added Parameters, Returns etc. entries.

Note that #2235 includes updates for roi.py since a lot of changes and extensions to the docstrings were already added there.

[astrofrog]

@dhomeier - could you rebase? Sorry for not reviewing this sonner!

[codecov]

Codecov Report

Merging #2237 (5604178) into main (55aca29) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #2237   +/-   ##
=======================================
  Coverage   88.07%   88.07%           
=======================================
  Files         247      247           
  Lines       23279    23279           
=======================================
  Hits        20502    20502           
  Misses       2777     2777           

Impacted Files	Coverage Δ
glue/core/application_base.py	82.53% <ø> (ø)
glue/core/command.py	93.85% <ø> (ø)
glue/core/component.py	95.85% <ø> (ø)
glue/core/component_id.py	89.24% <ø> (ø)
glue/core/component_link.py	86.48% <ø> (ø)
glue/core/coordinate_helpers.py	90.66% <ø> (ø)
glue/core/coordinates.py	90.62% <ø> (ø)
glue/core/data.py	91.66% <ø> (ø)
glue/core/data_collection.py	90.33% <ø> (ø)
glue/core/data_combo_helper.py	91.85% <ø> (ø)
... and 19 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 55aca29...5604178. Read the comment docs.

[dhomeier]

No problem! I did a cursory search for new function's docstrings added since, or any that I've missed before.

[dhomeier]

Beats me why the contracted form works in some cases like ~numpy.ndarray but just breaks the links in others.

[astrofrog]

Looks good! However the docs failures are related to this PR, so could you investigate? (I think just some incorrect intersphinx references)

[dhomeier]

Looks good! However the docs failures are related to this PR, so could you investigate? (I think just some incorrect intersphinx references)

Can you point me to an example where they are failing? I think the last build here was https://readthedocs.org/projects/glueviz/builds/15921389/

[astrofrog]

@dhomeier - ah I meant the Azure build, e.g. the tox py37-docs-pyqt513 config

[dhomeier]

Yeah, sorry, just found it – I had missed that among the other pyside + pyqt51x failures!

[dhomeier]

Warning, treated as error:
/home/vsts/work/1/s/.tox/py37-docs-pyqt513/lib/python3.7/site-packages/glue/core/data.py:docstring of glue.core.data.BaseCartesianData.compute_fixed_resolution_buffer:14:py:class reference target not found: glue.core.Data

Not quite an intersphinx issue then – that reference was indeed broken, missing the full class path. Still a mystery to me why the plain ~glue.core.Data version did not raise (but the links in http://docs.glueviz.org/en/stable/api/glue.core.data.BaseCartesianData.html#glue.core.data.BaseCartesianData.compute_fixed_resolution_buffer are all dead, so maybe numpydoc never looked at them).

[astrofrog]

@dhomeier - it looks like there might still be some issues as the Azure docs builds are still failing?

[dhomeier]

Yes, I realised I need to sphinx-build -Wn as well to track them all down!

[dhomeier]

Still a ton of warnings the likes of

docstring of glue.viewers.common.qt.toolbar.BasicToolbar.actionTriggered:2: WARNING: Inline emphasis start-string without end-string.

glue/viewers/common/qt/toolbar.py:docstring of glue.viewers.common.qt.toolbar.BasicToolbar.create:: WARNING: py:class reference target not found: PyQt5.sip.voidptr

As they are pretty much inherited from PyQt5.QtWidgets.QToolBar they seem a bit out of control; so I hope docs-test will let them pass through.

[astrofrog]

Looks great, thanks! For the reference issues related to Qt I usually add exceptions in conf.py but you could always add that in a separate PR if you like

[dhomeier]

Thanks, yes, seems a ('py:class', 'PyQt5.sip.voidptr') would already have done it, but apparently the Azure builds don't care about that – and fortunately neither throw up the "Inline emphasis start-string without end-string" stuff, which is not a nitpick afaict.