Merge pull request #813 from pllim/doc-nitpicky

DOC: Enable nitpicky in doc build

docs/conf.py

@@ -28,7 +28,7 @@
 import os
 import sys
 import datetime
-from pkg_resources import get_distribution
+import importlib.metadata as importlib_metadata
 
 try:
     from sphinx_astropy.conf.v1 import *  # noqa
@@ -76,10 +76,8 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
-package = get_distribution(project)
-
 # The full version, including alpha/beta/rc tags.
-release = package.version
+release = importlib_metadata.version(project)
 # The short X.Y version.
 version = '.'.join(release.split('.')[:2])
 
@@ -160,10 +158,11 @@
 github_issues_url = 'https://github.com/{0}/issues/'.format(setup_cfg['github_project'])
 
 # -- Turn on nitpicky mode for sphinx (to warn about references not found) ----
-#
-# nitpicky = True
-# nitpick_ignore = []
-#
+nitpicky = True
+
+# Do not populate this if you use nitpick-exceptions below.
+nitpick_ignore = []
+
 # Some warnings are impossible to suppress, and you can list specific references
 # that should be ignored in a nitpick-exceptions file which should be inside
 # the docs/ directory. The format of the file should be:
@@ -178,11 +177,15 @@
 #
 # Uncomment the following lines to enable the exceptions:
 #
-# for line in open('nitpick-exceptions'):
-#     if line.strip() == "" or line.startswith("#"):
-#         continue
-#     dtype, target = line.split(None, 1)
-#     target = target.strip()
-#     nitpick_ignore.append((dtype, six.u(target)))
-
+for line in open('nitpick-exceptions'):
+    if line.strip() == "" or line.startswith("#"):
+        continue
+    dtype, target = line.split(None, 1)
+    target = target.strip()
+    nitpick_ignore.append((dtype, target))
+
+# Extra intersphinx in addition to what is already in sphinx-astropy
 intersphinx_mapping['glue'] = ('http://docs.glueviz.org/en/stable/', None)
+intersphinx_mapping['glue_jupyter'] = ('https://glue-jupyter.readthedocs.io/en/stable/', None)
+intersphinx_mapping['specutils'] = ('https://specutils.readthedocs.io/en/stable/', None)
+intersphinx_mapping['spectral_cube'] = ('https://spectral-cube.readthedocs.io/en/stable/', None)

docs/cubeviz/displaycubes.rst

@@ -14,11 +14,11 @@ function. The indicators that the load machinery looks for in each HDU to
 populate the viewers are below (note that in all cases, header values are
 converted to lower case):
 
-    - Flux viewer: `hdu.name` is in the set `['flux', 'sci']`
-    - Uncertainty viewer: `hdu.header.keys()` includes "errtype" or `hdu.name` 
-      is in the set `['ivar', 'err', 'var', 'uncert']`
-    - Mask viewer: `hdu.data.dtype` is `np.int`, `np.uint` or `np.uint32`, or
-      `hdu.name` is in the set `['mask', 'dq']`
+    - Flux viewer: ``hdu.name`` is in the set ``['flux', 'sci']``
+    - Uncertainty viewer: ``hdu.header.keys()`` includes "errtype" or ``hdu.name``
+      is in the set ``['ivar', 'err', 'var', 'uncert']``
+    - Mask viewer: ``hdu.data.dtype`` is `int`, `numpy.uint` or `numpy.uint32`, or
+      ``hdu.name`` is in the set ``['mask', 'dq']``
 
 If any viewer fails to populate automatically, or if displaying 
 different data is desired, the user can manually select data for each viewer
@@ -72,12 +72,14 @@ and the resulting spectrum will be displayed in the 1d spectrum viewer at the bo
 There are other options available for region of interest. At the top of the User Interface,
 there is a section that says either "+ No selection (create new)" or "Subset n" where n is an integer
 that tells you which Subset is currently selected. To the right of this area, are red circles that allow
-you to change the method of region selection. The options are `replace`, `add`, `and`, `xor`, and `remove`.
-`replace` will remove the previously created selection and place the newly created subset.
-`add` allows you to create another subset that extends the existing subset.
-`and` only leaves behind the overlapping region between the existing subset and any additional subsets.
-`xor` only leaves behind the non-overlapping region between the existing subset and any additional subsets.
-`remove` will de-select any parts of the existing subset that overlaps with any additional subsets.
+you to change the method of region selection. The options are:
+
+* ``replace``: will remove the previously created selection and place the newly created subset.
+* ``add``: allows you to create another subset that extends the existing subset.
+* ``and``: only leaves behind the overlapping region between the existing subset and any additional subsets.
+* ``xor``: only leaves behind the non-overlapping region between the existing subset and any additional subsets.
+* ``remove``: will de-select any parts of the existing subset that overlaps with any additional subsets.
+
 You can use these options to further adjust the region of interest and adapt it to your use case.
 
 .. seealso::

docs/cubeviz/displayspectra.rst

@@ -14,5 +14,5 @@ below.
     `Displaying Spectra (Specviz) <https://jdaviz.readthedocs.io/en/latest/specviz/displaying.html>`_
         Documentation on displaying spectra in a 1D spectrum viewer.
 
-The functionality of the `Specviz` API can be accessed in Cubeviz via 
-the `specviz` attribute of the `Cubeviz` class, e.g. `cubeviz.specviz.get_spectra()`.
+The functionality of the `~jdaviz.configs.specviz.Specviz` API can be accessed in Cubeviz via
+the `jdaviz.configs.cubeviz.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``.

docs/cubeviz/import_data.rst

@@ -36,11 +36,11 @@ Importing data via the API
 
 Alternatively, if you are working in a coding environment like a Jupyter
 notebook, you have access to the Cubeviz helper class API. Using this API,
-you can load data into the application through code using the `load_data`
+you can load data into the application through code using the
+:meth:`~jdaviz.core.helpers.ConfigHelper.load_data`
 method, which takes as input either the name of a local file or a 
 :class:`~spectral_cube.SpectralCube` or :class:`~specutils.Spectrum1D` object.
 
     >>> from jdaviz import Cubeviz
     >>> cubeviz = Cubeviz()
-    >>> cubeviz.load_data("/Users/demouser/data/cube_file.fits") #doctest: +SKIP
-
+    >>> cubeviz.load_data("/Users/demouser/data/cube_file.fits")  # doctest: +SKIP

docs/cubeviz/notebook.rst

@@ -9,10 +9,11 @@ the following code in a cell of the notebook::
 
     >>> from jdaviz import Cubeviz
     >>> cubeviz = Cubeviz()
-    >>> cubeviz.app #doctest: +SKIP
+    >>> cubeviz.app  # doctest: +SKIP
 
 After running the code above, you can interact with the Cubeviz application from 
-subsequent notebook cells via the API methods attached to the `cubeviz` object,
+subsequent notebook cells via the API methods attached to the
+`~jdaviz.configs.cubeviz.helper.Cubeviz` object,
 for example loading data into the app as described in :ref:`cubeviz-import-data`.
 
 Data can also be accessed via the lower-level application interface that
@@ -23,8 +24,8 @@ attribute of the `~jdaviz.configs.cubeviz.helper.Cubeviz` helper class. For exam
      cubeviz.app.get_data_from_viewer('flux-viewer')
 
 This code can be used to access data from the different viewers, which is returned as a dictionary.
-The viewer options in the `cubeviz` configuration are `spectrum-viewer`, `flux-viewer`,
-`uncert-viewer`, and `mask-viewer`.
+The viewer options in the Cubeviz configuration are ``spectrum-viewer``, ``flux-viewer``,
+``uncert-viewer``, and ``mask-viewer``.
 Using the appropriate data label, the data in its native type can be returned from this dictionary like
 so::
 
@@ -35,6 +36,7 @@ Data can also be accessed directly from ``data_collection`` using the following
 
     cubeviz.app.data_collection[0]
 
-Which is returned as a `~glue.core.data.Data` object. The `data_collection` object
-can be indexed to return all available data (i.e. not just using `0` like in the
+Which is returned as a `~glue.core.data.Data` object. The
+`~glue.core.data_collection.DataCollection` object
+can be indexed to return all available data (i.e., not just using 0 like in the
 previous example).

docs/cubeviz/plugins.rst

@@ -67,20 +67,21 @@ also saved to a dataset with the label specified in the :guilabel:`Model Label`
     `Model Fitting <https://jdaviz.readthedocs.io/en/latest/specviz/plugins.html#model-fitting>`_
         Specviz documentation on fitting spectral models.
 
-As mentioned in the `specviz` documentation on model fitting, models can be accessed
-in a jupyter notebook by using the following code::
+As mentioned in the :ref:`specviz-model-fitting` section for Specviz, models can be accessed
+in a Jupyter notebook by using the following code::
 
     cubeviz.get_models(model_label="Model", x=10)
 
-Where the `model_label` parameter identifies which model should be returned and the `x` and
-`y` parameters identify specifically which spaxel fits are to be returned, for models
-applied to every spaxel using the :guilabel:`Apply to Cube` button. Leaving `x` or
-`y` as `None` will mean that the models fit to every spaxel across that axis will be
+Where the ``model_label`` keyword identifies which model should be returned and the ``x`` and
+``y`` keywords identify specifically which spaxel fits are to be returned, for models
+applied to every spaxel using the :guilabel:`Apply to Cube` button. Leaving ``x`` or
+``y`` as `None` will mean that the models fit to every spaxel across that axis will be
 returned. Model parameters can also be accessed using the following code::
 
     cubeviz.get_model_parameters(model_label="Model", y=52)
 
-With the parameters following the same pattern as the `get_models()` method.
+With the parameters following the same pattern as the
+:meth:`~jdaviz.core.helpers.ConfigHelper.get_models` method.
 
 Contours
 ========
@@ -135,7 +136,7 @@ Line Analysis
 .. _moment-maps:
 
 Moment Maps
-=============
+===========
 
 .. image:: ../img/moment1_map.png
 
@@ -147,7 +148,7 @@ a moment map. The order of the moment map (0, 1, 2, ...) indicates
 the power-law index to which the spectral axis is raised.  A 'moment 0' map
 gives the integrated flux over a spectral region. Similarly, 'moment 1'
 is the flux-weighted centroid (e.g. line center) and a 'moment 2'
-is the dispersion (e.g. wavelength or velocity dispersion)
+is the dispersion (e.g., wavelength or velocity dispersion)
 along the spectral axis.  Moments 3 and 4 are less commonly utilized,
 but correspond to the skewness and
 kurtosis of a spectral feature.
@@ -174,7 +175,7 @@ converted to velocity units before running the plugin if those units are
 desired for the output moment maps.
 
 Line or Continuum Maps
-===================================
+======================
 
 .. image:: ../img/moment0_line_map.png
 

docs/imviz/index.rst

@@ -8,7 +8,7 @@ Imviz
 #####
 
 Imviz is a tool for visualization and quick-look analysis for 2D astronomical
-images. Like the rest of `jdaviz`, it is written in the Python programming
+images. Like the rest of Jdaviz, it is written in the Python programming
 language, and therefore can be run anywhere Python is supported
 (see :doc:`../installation`). Imviz is built on top of the
 `Glupyter <https://glue-jupyter.readthedocs.io>`_ backend, providing a visual,

docs/imviz/notebook.rst

@@ -10,3 +10,9 @@ To run Imviz in a notebook::
     imviz = Imviz()
     imviz.app
 
+Imviz also provides programmatic access to its viewers using
+`Astrowidgets <https://astrowidgets.readthedocs.io/en/latest/>`_ API.
+For example::
+
+    viewer = imviz.app.get_viewer('viewer-1')
+    viewer.center_on((100, 100))

docs/known_bugs.rst

@@ -26,10 +26,10 @@ This can be fixed by reinstalling scikit-image::
     pip uninstall scikit-image
     conda install scikit-image
 
-The reason for this issue is that prebuilt binaries for `scikit-image` don't
+The reason for this issue is that prebuilt binaries for scikit-image don't
 work on Mac versions of 10.13 or older and conda installs an older
 version of scikit-image that works with those versions.
-Another way to get the up-to-date `scikit-image` version is::
+Another way to get the up-to-date scikit-image version is::
 
     pip install -U --no-binary scikit-image scikit-image.
 
@@ -39,8 +39,8 @@ first solution.
 On some platforms, install fails due to vispy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The 0.6.4 version of `vispy` fails to build for some combinations of
-platform/OS and Python versions.  `vispy` 0.6.5 has resolved this, but a
+The 0.6.4 version of vispy fails to build for some combinations of
+platform/OS and Python versions. vispy 0.6.5 has resolved this, but a
 workaround if you have an older version of vispy is to ensure you have a
 compatible version::
 

docs/mosviz/displayspectra.rst

@@ -10,8 +10,9 @@ with 2d spectra populating the top right viewer, and 1d spectra populating the v
     `Display Spectra <https://jdaviz.readthedocs.io/en/latest/specviz/displaying.html#>`_
         Specviz documentation on displaying spectra.
 
-The functionality of the `Specviz` API can be accessed in Moseviz via
-the `specviz` attribute of the `Mosviz` class, e.g. `mosviz.specviz.get_spectra()`.`
+The functionality of the Specviz API can be accessed in Mosviz via
+the `jdaviz.configs.mosviz.helper.Mosviz.specviz` attribute, e.g.,
+``mosviz.specviz.get_spectra()``.
 
 Pan/Zoom
 ========

docs/mosviz/import_data.rst

@@ -8,23 +8,25 @@ Currently, data must be imported into Mosviz using the API in the Jupyter notebo
 After initializing the app as explained in :ref:`mosviz-notebook`, 
 you must generate three lists containing the filenames for the 1D spectra, 
 2D spectra, and images in your dataset. These three lists are taken as arguments 
-to the Mosviz `load_data` method. An example is given below, where `file_dir` is a 
+to the :meth:`~jdaviz.configs.mosviz.helper.Mosviz.load_data` method.
+An example is given below, where ``file_dir`` is a
 directory that contains all the files for the dataset to be loaded::
 
+    >>> import glob
     >>> from jdaviz import Mosviz
     >>> mosviz = Mosviz()
-    >>> mosviz.app #doctest: +SKIP
+    >>> mosviz.app  # doctest: +SKIP
     >>> spectra_1d = []
     >>> spectra_2d = []
     >>> images = []
-    >>> for filename in glob("{}/*".format(file_dir)): #doctest: +SKIP
-    >>>     if "x1d" in filename: #doctest: +SKIP
-    >>>         spectra_1d.append(filename) #doctest: +SKIP
-    >>>     elif "s2d" in filename: #doctest: +SKIP
-    >>>         spectra_2d.append(filename) #doctest: +SKIP
-    >>>     elif "fits" in filename: #doctest: +SKIP
-    >>>         images.append(filename) #doctest: +SKIP
-    >>>     mosviz.load_data(spectra_1d, spectra_2d, images) #doctest: +SKIP
+    >>> for filename in glob.iglob(f"{file_dir}/*"):  # doctest: +SKIP
+    >>>     if "x1d" in filename:  # doctest: +SKIP
+    >>>         spectra_1d.append(filename)  # doctest: +SKIP
+    >>>     elif "s2d" in filename:  # doctest: +SKIP
+    >>>         spectra_2d.append(filename)  # doctest: +SKIP
+    >>>     elif "fits" in filename:  # doctest: +SKIP
+    >>>         images.append(filename)  # doctest: +SKIP
+    >>>     mosviz.load_data(spectra_1d, spectra_2d, images)  # doctest: +SKIP
 
 This example assumes that all 1D spectra have "x1d" in the filename, all 2D spectra
 have "s2d" in the filename, and any other FITS files in the directory are the 

docs/mosviz/notebook.rst

@@ -9,10 +9,11 @@ the following code in a cell of the notebook::
 
     >>> from jdaviz import Mosviz
     >>> mosviz = Mosviz()
-    >>> mosviz.app #doctest: +SKIP
+    >>> mosviz.app  # doctest: +SKIP
 
 After running the code above, you can interact with the Mosviz application from 
-subsequent notebook cells via the API methods attached to the `mosviz` object,
+subsequent notebook cells via the API methods attached to the
+`~jdaviz.configs.mosviz.helper.Mosviz` object,
 for example loading data into the app as described in :ref:`mosviz-import-data`.
 
 .. seealso::
@@ -21,20 +22,20 @@ for example loading data into the app as described in :ref:`mosviz-import-data`.
         Cubeviz documentation on data exporting.
 
 The `~jdaviz.configs.mosviz.helper.Mosviz` helper class can be used similarly to how
-`cubeviz` is used in the previous link.
-The viewers in `mosviz` that can be used that way are `image-viewer`, `spectrum-viewer`,
-and `spectrum-2d-viewer`.
+`~jdaviz.configs.cubeviz.helper.Cubeviz` is used in :ref:`cubeviz-notebook`.
+The viewers in Mosviz that can be used that way are ``image-viewer``, ``spectrum-viewer``,
+and ``spectrum-2d-viewer``.
 
-It is also possible to extract the contents of the table viewer via::
+It is also possible to extract the contents of the table viewer using
+`~jdaviz.configs.mosviz.helper.Mosviz.to_csv`::
 
     mosviz.to_csv(filename="MOS_data.csv", selected=False)
 
-Which will save the data from the `mosviz` table into a csv file named
-`filename`. If the `selected` parameter is set to `True`, only the checked
-rows in the table will be output. A previous csv file of the same name can
-be overwritten by setting the `overwrite` parameter to `True`.
-The contents of `table-viewer` can also be extracted to a notebook cell by
-running the following::
+Which will save the data from the Mosviz table into the given CSV filename.
+If the ``selected`` keyword is set to `True`, only the checked
+rows in the table will be output. A previous CSV file of the same name can
+be overwritten by setting the ``overwrite`` keyword to `True`.
+The contents of ``table-viewer`` can also be extracted to a notebook cell by
+running `~jdaviz.configs.mosviz.helper.Mosviz.to_table`::
 
     mosviz.to_table()
-

docs/mosviz/plugins.rst

@@ -67,6 +67,6 @@ A slit can be added to the image viewer by opening the Slit Overlay plugin and c
 The :guilabel:`Remove` button can be used to remove a slit once it has been applied to the image viewer.
 
 In order to plot a slit onto the image viewer, we need WCS information from an image and slit position from a 2D spectrum.
-WCS information is taken from the `meta` attribute of the :class:`~astropy.nddata.CCDData` object representing the data in the
-image viewer. The slit position is calculated using the `S_REGION` header extension value, located in the `meta` attribute of
-the :class:`~specutils.Spectrum1D` object that is active in the 2D spectrum viewer.
+The slit position is calculated using the ``S_REGION`` header extension value, located in the
+`~specutils.Spectrum1D.meta` attribute of the :class:`~specutils.Spectrum1D` object
+that is active in the 2D spectrum viewer.

docs/nitpick-exceptions

@@ -0,0 +1,5 @@
+# https://github.com/mariobuikhuizen/ipyvuetify/issues/180
+py:class ipyvuetify.VuetifyTemplate.VuetifyTemplate
+
+# https://github.com/glue-viz/glue-jupyter/issues/258
+py:class glue_jupyter.table.viewer.TableViewer

docs/notebook/export_data.rst

@@ -9,7 +9,7 @@ Specific instructions on exporting data from Jdaviz to your notebook vary slight
 Export Position Regions (Imviz)
 -------------------------------
 
-In `Imviz`, you can extract positional regions::
+In `~jdaviz.configs.imviz.helper.Imviz`, you can extract positional regions::
 
     regions = myviz.get_interactive_regions()
     regions
@@ -58,9 +58,9 @@ Export Data from Image Viewer
 
 In Cubeviz, three image viewers display your data:
 
- |   Top Left: `flux-viewer`
- |   Center: `uncert-viewer`
- |   Top Right: `mask-viewer`
+ |   Top Left: ``flux-viewer``
+ |   Center: ``uncert-viewer``
+ |   Top Right: ``mask-viewer``
 
 If you have modified your data cube and have new data in one of your image viewers, you can extract it.  To list the data avaialable in a particular viewer::