Use single-backticks when appropriate

Author: j9ac9k

doc/source/api_reference/graphicsItems/imageitem.rst

@@ -37,6 +37,8 @@ translation, scaling or rotations effects that persist for all later image data,
 user can also directly define and assign such a transform, as shown in the example
 below.
 
+.. _ImageItem_performance:
+
 Performance
 -----------
 

pyqtgraph/graphicsItems/ImageItem.py

@@ -1,4 +1,5 @@
 import os
+import pathlib
 import warnings
 from collections.abc import Callable
 
@@ -21,7 +22,18 @@
 
 
 class ImageItem(GraphicsObject):
-    """
+    """Graphics object used to display image data.
+
+    ImageItem can render images with 1, 3 or 4 channels, use lookup tables to apply
+    false colors to images, and users can either set levels limits, or rely on
+    the auto-sampling.
+
+    Performance can vary wildly based on the attributes of the inputs provided, see
+    :ref:`performance <ImageItem_performance>` for guidance if performance is an 
+    important factor.
+
+    There is optional `numba` and `cupy` support.
+
     **Bases:** :class:`pyqtgraph.GraphicsObject`
 
     Signals
@@ -93,23 +105,24 @@ def setCompositionMode(self, mode: QtGui.QPainter.CompositionMode):
             Composition of the item, often used when overlaying items.  Common
             options include:
 
-            * ``QPainter.CompositionMode.CompositionMode_SourceOver``
+            * `QPainter.CompositionMode.CompositionMode_SourceOver`
               Image replaces the background if it is opaque. Otherwise, it uses the
               alpha channel to blend the image with the background, default
-            * ``QPainter.CompositionMode.CompositionMode_Overlay`` Image color is
+            * `QPainter.CompositionMode.CompositionMode_Overlay` Image color is
               mixed with the background color to reflect the lightness or darkness of
               the background
-            * ``QPainter.CompositionMode.CompositionMode_Plus`` Both the alpha and
+            * `QPainter.CompositionMode.CompositionMode_Plus` Both the alpha and
               color of the image and background pixels are added together.
-            * ``QPainter.CompositionMode.CompositionMode_Plus`` The output is the
+            * `QPainter.CompositionMode.CompositionMode_Plus` The output is the
               image color multiplied by the background.
 
             See :class:`QPainter.CompositionMode <QPainter.CompositionMode>` in the Qt
             documentation for more options and details
         
         See Also
         --------
-        :class:`QPainter.CompositionMode <QPainter.CompositionMode>`
+        :class:`QPainter.CompositionMode <QPainter.CompositionMode>` : Details all the
+            possible composition mode options accepted.
         """
         self.paintMode = mode
         self.update()
@@ -181,7 +194,7 @@ def setLevels(self, levels: npt.ArrayLike | None, update: bool=True):
     def getLevels(self) -> numpy.ndarray | None:
         """
         Returns the array representing the current level settings. See
-        :func:`setLevels`. When ``autoLevels`` is active, the format is
+        :func:`setLevels`. When `autoLevels` is active, the format is
         ``[blackLevel, whiteLevel]``.
         """
         return self.levels
@@ -199,8 +212,7 @@ def setColorMap(self, colorMap: colormap.ColorMap | str):
         Raises
         ------
         TypeError
-            Raised when ``colorMap`` is not of type ``str`` or
-            :class:`~pyqtgraph.ColorMap`
+            Raised when `colorMap` is not of type `str` or :class:`~pyqtgraph.ColorMap`
         """
         if isinstance(colorMap, colormap.ColorMap):
             self._colorMap = colorMap
@@ -220,7 +232,7 @@ def getColorMap(self) -> colormap.ColorMap | None:
         return self._colorMap
 
     def setLookupTable(self, lut: npt.ArrayLike | Callable, update: bool=True):
-        """Sets lookup table ``lut`` to use for false color display of a monochrome
+        """Sets lookup table `lut` to use for false color display of a monochrome
         image. See :func:`makeARGB <pyqtgraph.functions.makeARGB>` for more 
         information on how this is used.
 
@@ -230,7 +242,7 @@ def setLookupTable(self, lut: npt.ArrayLike | Callable, update: bool=True):
         Parameters
         ----------
         lut : array_like or callable
-            ``lut`` can be a callable that accepts the current image as an argument and
+            `lut` can be a callable that accepts the current image as an argument and
             returns the lookup table to use.
         update : bool, optional
             Update the intermediate image, by default True.
@@ -269,9 +281,9 @@ def setAutoDownsample(self, active: bool=True):
         active : bool, optional
             If `active` is `True`, the image is automatically downsampled to match the
             screen resolution. This improves performance for large images and reduces
-            aliasing. If ``autoDownsample`` is not specified, then ImageItem will
+            aliasing. If `autoDownsample` is not specified, then ImageItem will
             choose whether to downsample the image based on its size. ``False``
-            disables automatic downsampling. by default True    
+            disables automatic downsampling. by default ``True``
         """
         self.autoDownsample = active
         self._renderRequired = True
@@ -355,7 +367,7 @@ def setOpts(self, update: bool=True, **kargs):
 
     def setRect(self, *args):
         """Sets translation and scaling of this ImageItem to display the current image
-        within the rectangle given as ``rect`` (:class:`QRect` or :class:`QRectF`), or
+        within the rectangle given as `rect` (:class:`QRect` or :class:`QRectF`), or
         described by parameters `x, y, w, h`, defining starting position, width and
         height.
 
@@ -372,7 +384,7 @@ def setRect(self, *args):
 
         See Also
         --------
-        :class:`QRectF`
+        :class:`QRectF` : See constructor methods for allowable ``*args``
         """
         if not args:
             # reset scaling and rotation when called without argument
@@ -439,8 +451,8 @@ def setImage(
             search subsamples the images and may miss individual bright or dark points
             in the data set. If `False`, the search will be omitted.
 
-            The default is `False` if a ``levels`` keyword argument is given, and
-            `True` otherwise.
+            The default is ``False`` if a `levels` keyword argument is given, and
+            ``True`` otherwise.
         levelSamples : int, default 65536
             When determining minimum and maximum values, ImageItem only inspects a
             subset of pixels no larger than this number. Setting this larger than the
@@ -457,7 +469,7 @@ def setImage(
             imageitem.setImage(imagedata.T)
         
         or the interpretation of the data can be changed locally through the
-        ``axisOrder`` keyword or by changing the `imageAxisOrder`
+        `axisOrder` keyword or by changing the `imageAxisOrder`
         :ref:`global configuration option <apiref_config>`
 
         For more information on how the image is processed before displaying, see
@@ -740,20 +752,20 @@ def paint(self, p, *args):
             p.setPen(self.border)
             p.drawRect(self.boundingRect())
 
-    def save(self, fileName: str, *args):
+    def save(self, fileName: str | pathlib.Path, *args):
         """Saves this image to file. Note that this saves the visible image
         (after scale/color changes), not the original data.
 
         Parameters
         ----------
-        fileName : str
+        fileName : str or pathlib.Path
             path to save the image to
         *args : tuple
             arguments that are passed to :meth:`QImage.save <QImage.save>`
             
         See Also
         --------
-        :meth:`QImage.save <QImage.save>`
+        :meth:`QImage.save <QImage.save>` : ``*args`` is relayed to this method
         """
 
         if self._renderRequired:
@@ -775,15 +787,15 @@ def getHistogram(
         Parameters
         ----------
         bins : int or str, optional
-            The ``bins`` argument and any extra keyword arguments are passed to
+            The `bins` argument and any extra keyword arguments are passed to
             :func:`numpy.histogram()`. If ``bins == 'auto'``, a bin number is
             automatically chosen based on the image characteristics, by default
-            ``'auto'``
+            `'auto'`
         step : str or int, optional
-            The ``step`` argument causes pixels to be skipped when computing the
+            The `step` argument causes pixels to be skipped when computing the
             histogram to save time. If `step` is 'auto', then a step is chosen such
             that the analyzed data has dimensions approximating `targetImageSize`
-            for each axis, by default ``'auto'``
+            for each axis, by default `'auto'`
         perChannel : bool, optional
             If ``True``, then a histogram is computed for each channel, 
             and the output is a list of the results, by default ``False``
@@ -803,7 +815,7 @@ def getHistogram(
 
         See Also
         --------
-        numpy.histogram
+        numpy.histogram : describes return format in greater detail
         """        
 
         if 'targetHistogramSize' in kwds:
@@ -873,12 +885,15 @@ def setPxMode(self, b: bool):
         If ``True``, the item will not inherit any scale or rotation transformations from its
         parent items, but its position will be transformed as usual.
 
-        Read the description of ``ItemIgnoresTransformations`` member of the
-        :class:`QGraphicsItem.GraphicsItemFlag` enum in the Qt documentation
+        Parameters
+        ----------
+        b : bool
+            Enable pixel model, thus ignoring transformations
 
         See Also
         --------
-        :class:`QGraphicsItem.GraphicsItemFlag`
+        :class:`QGraphicsItem.GraphicsItemFlag` : Read the description of 
+          `ItemIgnoresTransformations` for more information
 
         """
         self.setFlag(
@@ -976,7 +991,7 @@ def hoverEvent(self, ev):
             if self.drawKernel is not None and ev.acceptDrags(
                 QtCore.Qt.MouseButton.LeftButton
             ):
-                 # we don't use the click, but we also don't want anyone else to use it
+                # we don't use the click, but we also don't want anyone else to use it
                 ev.acceptClicks(QtCore.Qt.MouseButton.LeftButton)
                 ev.acceptClicks(QtCore.Qt.MouseButton.RightButton)
             elif self.removable: