Backport PR #881 on branch 2.3 (Nitpick documentation)

docs/conf.py

@@ -103,9 +103,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "sunpy"
-
 html_logo = png_icon = 'logo/ndcube.png'
-
 html_favicon = 'logo/favicon.png'
 
 # Render inheritance diagrams in SVG
@@ -136,10 +134,6 @@
 
 # -- Other options ----------------------------------------------------------
 
-napoleon_use_rtype = False
-napoleon_google_docstring = False
-napoleon_use_param = False
-
 nitpicky = True
 # This is not used. See docs/nitpick-exceptions file for the actual listing.
 nitpick_ignore = []
@@ -172,6 +166,4 @@
 ogp_image = "https://github.com/sunpy/ndcube/raw/main/docs/logo/ndcube.png"
 ogp_use_first_image = True
 ogp_description_length = 160
-ogp_custom_meta_tags = [
-    '<meta property="og:ignore_canonical" content="true" />',
-]
+ogp_custom_meta_tags = ('<meta property="og:ignore_canonical" content="true" />',)

docs/nitpick-exceptions

@@ -1,22 +1,122 @@
-# Numpy?
-py:obj NDData
-py:class NDDataRef
-py:class NDDataArray
-py:obj NDDataRef
-py:obj NDDataArray
+# Prevents sphinx nitpicky mode picking up on optional
+# (see https://github.com/sphinx-doc/sphinx/issues/6861)
+# Even if it was "fixed", still broken
+py:class optional
+# See https://github.com/numpy/numpy/issues/10039
+py:obj numpy.datetime64
+# There's no specific file or function classes to link to
+py:class (Unit('deg'), Unit('pix'))
+py:class (Unit('Mm'), None)
 py:class any type
+py:class array-like
+py:class file object
+py:class function
+py:class path-like
+py:class str-like
+py:class time-like
+py:class Unit
+py:class Unit('%')
+py:class Unit('Angstrom')
+py:class Unit('arcsec / pix')
+py:class Unit('arcsec')
+py:class Unit('deg')
+py:class Unit('pix')
+py:class Unit('s')
+py:class Unit('W / m2')
+py:class Unit('m')
+py:obj function
+py:class iterable
+py:class iterables
+py:obj iterable
+py:obj iterables
+py:obj parfive
+py:mod parfive
+py:obj astropy.io.fits.hdu.base.ExtensionHDU
+
 # Raised by core Python code
-py:class D[k] if k in D, else d.  d defaults to None.
 py:class a set-like object providing a view on D's items
 py:class a set-like object providing a view on D's keys
+py:class a shallow copy of D
 py:class an object providing a view on D's values
 py:class D[k] if k in D, else d.  d defaults to None.
-py:class a set-like object providing a view on D's items
-py:class a set-like object providing a view on D's keys
-py:class an object providing a view on D's values
 py:class None.  Remove all items from D.
-py:class a shallow copy of D
-py:class v, remove specified key and return the corresponding value.
 py:class None.  Update D from mapping/iterable E and F.
-# Comes from astropy? psf
+py:class v, remove specified key and return the corresponding value.
+
+# This comes from Map.wcs
+py:class prop
+py:class Maxwell
+
+# These come from astropy.coordinates.baseframe.represent_as
+py:class data
+py:class keyword only
+py:class keyword-only
+py:class string
+py:class subclass of BaseRepresentation
+
+# These come from astropy QTable
+py:class list of lists
+py:class list of list
+py:class numpy ndarray
+py:class numpy ndarray
+py:class Table
+py:class table-like object
+
+# numpy inherited docstrings
+py:obj a
+py:obj a.size == 1
+py:obj args
+py:obj dtype
+py:obj n
 py:obj ndarray
+
+# other classes and functions that cannot be linked to
+py:class astropy.table.column.BaseColumn
+py:class docutils.parsers.rst.Directive
+py:class numpy.core.records.recarray
+py:class numpy.ma.core.MaskedArray
+py:class numpy.ma.mvoid
+py:class numpy.void
+py:class pandas.DataFrame
+py:class xmlrpc.client.Error
+py:class xmlrpc.client.Fault
+py:class xmlrpclib.Error
+py:class xmlrpclib.Fault
+py:obj aiohttp.ClientResponse
+py:obj astropy.visualization.wcsaxes.coordinates_map.CoordinatesMap.grid
+py:obj data
+py:obj numpy.ma.core.MaskedArray
+py:obj pkg_resources.parse_version
+py:obj sunpy.extern.parse.parse
+
+# Pending on python docs links issue #11975
+py:class classmethod
+py:class list
+py:meth list.pop
+py:obj Artist
+py:obj AttributeError
+py:obj BboxBase
+py:obj int
+py:obj list.append
+py:obj list.append
+py:obj list.count
+py:obj list.extend
+py:obj list.index
+py:obj list.insert
+py:obj list.remove
+py:obj NotImplementedError
+py:obj NotImplementedError
+py:obj RendererBase
+py:obj RuntimeError
+py:obj text
+py:obj Text
+
+# like-types
+py:class dict-like
+
+# NDData
+py:obj NDData
+py:class NDDataRef
+py:class NDDataArray
+py:obj NDDataRef
+py:obj NDDataArray

ndcube/ndcube.py

@@ -357,11 +357,11 @@ class NDCubeBase(NDCubeABC, astropy.nddata.NDData, NDCubeSlicingMixin):
         that valid data points are marked by `False` and invalid ones with `True`.
         Defaults to `None`.
 
-    meta : dict-like object, optional
+    meta : dict-like, optional
         Additional meta information about the dataset. If no meta is provided
         an empty dictionary is created.
 
-    unit : Unit-like or `str`, optional
+    unit : `astropy.units.Unit` or `str`, optional
         Unit for the dataset. Strings that can be converted to a `~astropy.units.Unit` are allowed.
         Default is `None` which results in dimensionless units.
 
@@ -749,11 +749,11 @@ def reproject_to(self,
             or `astropy.io.fits.Header`
             The WCS object to which the `ndcube.NDCube` is to be reprojected.
 
-        algorithm: {'interpolation' | 'adaptive' | 'exact'}
+        algorithm: `str`, optional
             The algorithm to use for reprojecting.
-            When set to "interpolation" `~reproject.reproject_interp` is used,
-            when set to "adaptive" `~reproject.reproject_adaptive` is used and
-            when set to "exact" `~reproject.reproject_exact` is used.
+            When set to "interpolation" `~reproject.reproject_interp` is used.
+            When set to "adaptive" `~reproject.reproject_adaptive` is used.
+            When set to "exact" `~reproject.reproject_exact` is used.
 
         shape_out: `tuple`, optional
             The shape of the output data array. The ordering of the dimensions must follow NumPy
@@ -876,11 +876,11 @@ class NDCube(NDCubeBase):
         that valid data points are marked by False and invalid ones with True.
         Defaults to None.
 
-    meta : dict-like object, optional
+    meta : dict-like, optional
         Additional meta information about the dataset. If no meta is provided
         an empty collections.OrderedDict is created. Default is None.
 
-    unit : Unit-like or str, optional
+    unit : `astropy.units.Unit` or str, optional
         Unit for the dataset. Strings that can be converted to a Unit are allowed.
         Default is None.
 
@@ -910,7 +910,7 @@ class NDCube(NDCubeBase):
     # last moment.
     plotter = PlotterDescriptor(default_type="mpl_plotter")
     """
-    A `~.MatplotlibPlotter` instance providing visualization methods.
+    A ~ndcube.visualization.mpl_plotter.MatplotlibPlotter` instance providing visualization methods.
 
     The type of this attribute can be changed to provide custom visualization functionality.
     """

ndcube/ndcube_sequence.py

@@ -424,6 +424,12 @@ class NDCubeSequence(NDCubeSequenceBase):
         This enables the "cube_like" methods to be used, e.g.
         `ndcube.NDCubeSequence.index_as_cube` which slices the sequence as though it
         were a single cube concatenated along the common axis.
+
+    Attributes
+    ----------
+    common_axis_extra_coords
+    array_axis_physical_axis_types
+    cube_like_world_axis_physical_axis_types
     """
     # We special case the default mpl plotter here so that we can only import
     # matplotlib when `.plotter` is accessed and raise an ImportError at the

ndcube/utils/collection.py

@@ -139,9 +139,9 @@ def assert_aligned_axes_compatible(data_dimensions1, data_dimensions2, data_axes
 
     Parameters
     ----------
-    data_dimensions1: tuple of ints
+    data_dimensions1: `tuple` of `int`
         The dimension lengths of data cube 1.
-    data_dimensions2: tuple of ints
+    data_dimensions2: `tuple` of `int`
         The dimension lengths of data cube 2.
     data_axes1: `tuple` of `int`
         The aligned axes of data cube 1.

ndcube/utils/cube.py

@@ -249,9 +249,9 @@ def propagate_rebin_uncertainties(uncertainty, data, mask, operation, operation_
 
     Returns
     -------
-    new_uncertainty: same type as uncertainty input.
-        The propagated uncertainty. Same shape as input uncertainty without its
-        first dimension.
+    new_uncertainty: `astropy.nddata.NDUncertainty`
+        The propagated uncertainty.
+        Same shape as input uncertainty without its first dimension.
     """
     flat_axis = 0
     operation_is_mean = True if operation in {np.mean, np.nanmean} else False