DOC: a dearth of docstrings

[bmorris3]

I've noticed a bunch of public classes and methods don't have docstrings in jdaviz, even though they are often heavily featured in the narrative docs. It'd be great if someone drafted up docstrings (and I'd be happy to volunteer).

When building the docs (cd docs && make html), these are the classes and methods that are directly mentioned in the narrative docs but do not have a docstring:

/Users/bmmorris/git/jdaviz/jdaviz/configs/cubeviz/helper.py:docstring of jdaviz.configs.cubeviz.helper.CubeViz:1: WARNING: py:class reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/cubeviz/helper.py:docstring of jdaviz.configs.cubeviz.helper.CubeViz:2: WARNING: py:obj reference target not found: Cubeviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/mosviz/helper.py:docstring of jdaviz.configs.mosviz.helper.MosViz:1: WARNING: py:class reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/mosviz/helper.py:docstring of jdaviz.configs.mosviz.helper.MosViz:2: WARNING: py:obj reference target not found: Mosviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/specviz/helper.py:docstring of jdaviz.configs.specviz.helper.SpecViz:1: WARNING: py:class reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/specviz/helper.py:docstring of jdaviz.configs.specviz.helper.SpecViz:2: WARNING: py:obj reference target not found: Specviz
/Users/bmmorris/git/jdaviz/docs/api/jdaviz.configs.specviz2d.helper.Specviz2d.rst:14:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/docstring of jdaviz.configs.specviz2d.helper.Specviz2d.specviz:2: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/displayspectra.rst:17: WARNING: py:class reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/displayspectra.rst:17: WARNING: py:meth reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz.specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/import_data.rst:71: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/mosviz/displayspectra.rst:13: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.specviz
/Users/bmmorris/git/jdaviz/docs/mosviz/import_data.rst:58: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.load_data
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:16: WARNING: py:class reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:26: WARNING: py:class reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:26: WARNING: py:class reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:31: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz.to_csv
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:38: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.to_table
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:16: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.update_column
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:19: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_1d
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:19: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_2d
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:26:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:61:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:75:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:113: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.x_limits
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:113: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.y_limits
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:131: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.autoscale_x
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:131: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.autoscale_y
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:137: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.flip_x
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:137: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.flip_y
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:156: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.get_spectral_regions
/Users/bmmorris/git/jdaviz/docs/specviz/export_data.rst:19: WARNING: py:class reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:49: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:68: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:121: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:143: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/plugins.rst:208: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.get_spectra

[pllim]

Argh, did we not turn nitpicky on?

[pllim]

Wait, we did. So how???

jdaviz/docs/conf.py

Line 236 in cef3a55

nitpicky = True

[bmorris3]

@pllim Well now I'm confused because these warnings don't appear in the RTD build. The stdout I posted above was from my local machine.

[pllim]

Did you do a clean build?

cd docs
make clean
make html

[bmorris3]

Yes, I did a clean build. On main, I get the following warnings

sphinx warnings

/Users/bmmorris/git/jdaviz/jdaviz/configs/cubeviz/helper.py:docstring of jdaviz.configs.cubeviz.helper.CubeViz:1: WARNING: py:class reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/cubeviz/helper.py:docstring of jdaviz.configs.cubeviz.helper.CubeViz:1: WARNING: py:obj reference target not found: Cubeviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/mosviz/helper.py:docstring of jdaviz.configs.mosviz.helper.MosViz:1: WARNING: py:class reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/mosviz/helper.py:docstring of jdaviz.configs.mosviz.helper.MosViz:1: WARNING: py:obj reference target not found: Mosviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/specviz/helper.py:docstring of jdaviz.configs.specviz.helper.SpecViz:1: WARNING: py:class reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/specviz/helper.py:docstring of jdaviz.configs.specviz.helper.SpecViz:1: WARNING: py:obj reference target not found: Specviz
/Users/bmmorris/git/jdaviz/docs/api/jdaviz.configs.specviz2d.helper.Specviz2d.rst:14:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/jdaviz/configs/specviz2d/helper.py:docstring of jdaviz.configs.specviz2d.helper.Specviz2d.specviz:1: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/displayspectra.rst:17: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/displayspectra.rst:17: WARNING: py:obj reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz.specviz
/Users/bmmorris/git/jdaviz/docs/cubeviz/import_data.rst:71: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/mosviz/displayspectra.rst:13: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz.specviz
/Users/bmmorris/git/jdaviz/docs/mosviz/import_data.rst:50: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.load_data
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:14: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:24: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:24: WARNING: py:obj reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:29: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz.to_csv
/Users/bmmorris/git/jdaviz/docs/mosviz/notebook.rst:34: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz.to_table
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:16: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.update_column
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:19: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_1d
/Users/bmmorris/git/jdaviz/docs/mosviz/redshift.rst:19: WARNING: py:meth reference target not found: jdaviz.configs.mosviz.helper.Mosviz.get_spectrum_2d
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:26:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.cubeviz.helper.Cubeviz
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:61:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.mosviz.helper.Mosviz
/Users/bmmorris/git/jdaviz/docs/reference/api.rst:75:<autosummary>:1: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:113: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.x_limits
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:113: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.y_limits
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:131: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.autoscale_x
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:131: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.autoscale_y
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:137: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.flip_x
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:137: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.flip_y
/Users/bmmorris/git/jdaviz/docs/specviz/displaying.rst:156: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.get_spectral_regions
/Users/bmmorris/git/jdaviz/docs/specviz/export_data.rst:19: WARNING: py:obj reference target not found: jdaviz.configs.specviz.helper.Specviz
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:47: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:64: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:113: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/import_data.rst:133: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.load_spectrum
/Users/bmmorris/git/jdaviz/docs/specviz/plugins.rst:208: WARNING: py:meth reference target not found: jdaviz.configs.specviz.helper.Specviz.get_spectra

with an env summarized by the freeze below:

$ pip3 freeze | grep "sphinx"
astropy-sphinx-theme==1.1
sphinx-astropy==1.7.0
sphinx-automodapi==0.14.1
sphinx-gallery==0.11.1
sphinx-rtd-theme==1.0.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5

and Sphinx v5.3.0.

[pllim]

What if you downgrade to Sphinx v5.1.1 and try a clean doc build again? My Sphinx is a little behind because of astropy (long story). I don't see the warnings on my end.

[pllim]

Is your install an editable install? Dev install? Stable install?

[bmorris3]

I was using an editable install on main. Here are some of your suggestions that I tried, none of them prevented the warnings:

• install jdaviz with pip install . ❌
• install jdaviz with pip install . and downgrade to sphinx==5.1.1 ❌
• install jdaviz with python setup.py develop (with either sphinx 5.1.1 or 5.3.0) ❌
• install jdaviz with pip3 install .[doc] ❌

[pllim]

That is so weird! Obviously you have something that RTD and I both do not. But what is it? 🤯

[pllim]

Are you on a Mac? I know that sometimes Mac and Windows can be case-insensitive, causing bogus warnings in doc build. Do you have access to Linux? Can you try build the doc on Linux and see if warnings go away?

[bmorris3]

Yes I'm on a mac, and unfortunately I don't have easy access to another platform.