docs: minor docs fixups to help with sphinx warnings and errors (#4427)

Signed-off-by: Larry Gritz <[email protected]>
Signed-off-by: Zach Lewis <[email protected]>

src/doc/Doxyfile

@@ -2576,3 +2576,5 @@ GENERATE_LEGEND        = YES
 # This tag requires that the tag HAVE_DOT is set to YES.
 
 DOT_CLEANUP            = YES
+
+CLANG_ASSISTED_PARSING = YES

src/doc/builtinplugins.rst

@@ -1293,29 +1293,28 @@ control aspects of the writing itself:
    * - ``jpegxl:use_boxes``
      - int (bool)
      - If nonzero, will enable metadata (Exif, XMP, jumb, iptc) writing to the
-     output file. Default is 1.
+       output file. Default is 1.
    * - ``jpegxl:compress_boxes``
      - int (bool)
      - If nonzero, will enable metadata compression. Default is 1.
    * - ``jpegxl:exif_box``
      - int (bool)
      - If nonzero, will enable Exif metadata writing to the output file.
-     Default is 1.
+       Default is 1.
    * - ``jpegxl:xmp_box``
      - int (bool)
      - If nonzero, will enable XMP metadata writing to the output file.
-     Default is 1.
+       Default is 1.
    * - ``jpegxl:jumb_box``
      - int (bool)
      - If nonzero, will enable JUMBF metadata writing to the output file.
-     Default is 0.
-     (dows not supported at this moment in OIIO)
+       Default is 0. (dows not supported at this moment in OIIO)
    * - ``jpegxl:iptc_box``
      - int (bool)
      - If nonzero, will enable IPTC metadata writing to the output file.
-     Default is 0.
-     (Do not work as expected at this moment. Box is written but content
-     unreadable in exif readers)
+       Default is 0.
+       (Does not work as expected at this moment. Box is written but content
+       unreadable in exif readers.)
 
 .. _sec-bundledplugins-ffmpeg:
 

src/doc/imagebuf.rst

@@ -47,8 +47,8 @@ Making an empty or uninitialized ImageBuf
 Constructing a readable ImageBuf
 --------------------------------
 
-.. doxygenfunction:: OIIO::ImageBuf::ImageBuf(string_view name, int subimage = 0, int miplevel = 0, ImageCache *imagecache = nullptr, const ImageSpec *config = nullptr, Filesystem::IOProxy *ioproxy = nullptr)
-.. doxygenfunction:: OIIO::ImageBuf::reset(string_view name, int subimage = 0, int miplevel = 0, ImageCache *imagecache = nullptr, const ImageSpec *config = nullptr, Filesystem::IOProxy *ioproxy = nullptr)
+.. doxygenfunction:: OIIO::ImageBuf::ImageBuf(string_view name, int subimage = 0, int miplevel = 0, std::shared_ptr<ImageCache> imagecache = {}, const ImageSpec *config = nullptr, Filesystem::IOProxy *ioproxy = nullptr)
+.. doxygenfunction:: OIIO::ImageBuf::reset(string_view name, int subimage = 0, int miplevel = 0, std::shared_ptr<ImageCache> imagecache = {}, const ImageSpec *config = nullptr, Filesystem::IOProxy *ioproxy = nullptr)
 
 
 Constructing a writable ImageBuf
@@ -271,9 +271,9 @@ Cons/Limitations:
   this approach, especially for operations where you expect inputs to be float
   typically.
 
-.. doxygenfunction:: perpixel_op(const ImageBuf &src, bool (*op)(span<float>, cspan<float>), int prepflags = ImageBufAlgo::IBAprep_DEFAULT, int nthreads = 0)
+.. doxygenfunction:: perpixel_op(const ImageBuf &src, function_view<bool(span<float>, cspan<float>)> op, KWArgs options = {})
 
-.. doxygenfunction:: perpixel_op(const ImageBuf &srcA, const ImageBuf &srcB, bool (*op)(span<float>, cspan<float>, cspan<float>), int prepflags = ImageBufAlgo::IBAprep_DEFAULT, int nthreads = 0)
+.. doxygenfunction:: perpixel_op(const ImageBuf &srcA, const ImageBuf& srcB, function_view<bool(span<float>, cspan<float>, cspan<float>)> op, KWArgs options = {})
 
 Examples:
 

src/doc/oiiotool.rst

@@ -241,7 +241,7 @@ contents of an expression may be any of:
 
 To illustrate how this works, consider the following command, which trims
 a four-pixel border from all sides and outputs a new image prefixed with
-"cropped_", without needing to know the resolution or filename of the
+"`cropped_`", without needing to know the resolution or filename of the
 original image::
 
     oiiotool input.exr -cut "{TOP.width-2*4}x{TOP.height-2*4}+{TOP.x+4}+{TOP.y+4}" \
@@ -2781,8 +2781,7 @@ current top image.
       `max=` *vals*
         Specify the maximum range value(s), default 1.0.
       `scontrast=` *vals*
-        Specify sigmoidal contrast slope value(s),
-      default 1.0.
+        Specify sigmoidal contrast slope value(s), default 1.0.
       `sthresh=` *vals*
         Specify sigmoidal threshold value(s) giving the position of maximum
         slope, default 0.5.
@@ -4113,11 +4112,11 @@ current top image.
            -fill:topleft=.1,.1,.1:topright=1,0,0:bottomleft=0,1,0:botromright=0,0,1 \
                640x480 -o gradient.tif
 
-    .. |textimg1| image:: figures/gradient.jpg
+    .. |gradimg1| image:: figures/gradient.jpg
        :width: 2.0 in
-    .. |textimg2| image:: figures/gradienth.jpg
+    .. |gradimg2| image:: figures/gradienth.jpg
        :width: 2.0 in
-    .. |textimg2| image:: figures/gradient4.jpg
+    .. |gradimg3| image:: figures/gradient4.jpg
        :width: 2.0 in
     ..
 
@@ -4175,7 +4174,7 @@ current top image.
        :width: 2.0 in
     .. |textimg2| image:: figures/textcentered.jpg
        :width: 2.0 in
-    .. |textimg2| image:: figures/textshadowed.jpg
+    .. |textimg3| image:: figures/textshadowed.jpg
        :width: 2.0 in
     ..
     

src/include/OpenImageIO/imagebuf.h

@@ -1027,7 +1027,7 @@ class OIIO_API ImageBuf {
     /// spec in the ImageBuf to reset the "full" image size (a.k.a.
     /// "display window") to
     ///
-    ///     [xbegin,xend) x [ybegin,yend) x [zbegin,zend)`
+    /// `[xbegin,xend) x [ybegin,yend) x [zbegin,zend)`
     ///
     /// This does not affect the size of the pixel data window.
     void set_full(int xbegin, int xend, int ybegin, int yend, int zbegin,