From 114c6c8046f6652901c8f26c1c6ccdc7ead6de47 Mon Sep 17 00:00:00 2001 From: Stuart Mumford Date: Thu, 2 Oct 2025 10:01:54 +0100 Subject: [PATCH] Backport PR #881: Nitpick documentation --- docs/conf.py | 10 +-- docs/nitpick-exceptions | 126 +++++++++++++++++++++++++++++++++---- ndcube/ndcube.py | 18 +++--- ndcube/ndcube_sequence.py | 6 ++ ndcube/utils/collection.py | 4 +- ndcube/utils/cube.py | 6 +- 6 files changed, 134 insertions(+), 36 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f72cdbce5..6716b560c 100644 --- a/docs/conf.py +++ b/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 = [ - '', -] +ogp_custom_meta_tags = ('',) diff --git a/docs/nitpick-exceptions b/docs/nitpick-exceptions index 42e4f8cbb..cf555dca3 100644 --- a/docs/nitpick-exceptions +++ b/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 diff --git a/ndcube/ndcube.py b/ndcube/ndcube.py index 12b93936c..7753d18b0 100644 --- a/ndcube/ndcube.py +++ b/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. """ diff --git a/ndcube/ndcube_sequence.py b/ndcube/ndcube_sequence.py index 0a40a8ca4..c32de7fb3 100644 --- a/ndcube/ndcube_sequence.py +++ b/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 diff --git a/ndcube/utils/collection.py b/ndcube/utils/collection.py index ac01649ba..c9a84e6e8 100644 --- a/ndcube/utils/collection.py +++ b/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. diff --git a/ndcube/utils/cube.py b/ndcube/utils/cube.py index f4864f091..8233e41f0 100644 --- a/ndcube/utils/cube.py +++ b/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