From 22d504ddfb5eb545fad4a62ca5dcce693de0d393 Mon Sep 17 00:00:00 2001
From: Larry Gritz <lg@larrygritz.com>
Date: Sat, 3 May 2025 11:04:59 -0700
Subject: [PATCH] docs: Online docs improvements, mostly formatting

Signed-off-by: Larry Gritz <lg@larrygritz.com>
---
 src/doc/Doxyfile                     |  3 ++-
 src/doc/requirements.txt             |  4 ++--
 src/doc/texturesys.rst               |  2 +-
 src/include/OpenImageIO/image_span.h | 10 +++++-----
 src/include/OpenImageIO/span.h       |  2 ++
 5 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/doc/Doxyfile b/src/doc/Doxyfile
index ddc55a4b05..ee40d48dcd 100644
--- a/src/doc/Doxyfile
+++ b/src/doc/Doxyfile
@@ -2197,12 +2197,13 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OIIO_CONST_FUNC= \
                          OIIO_MAYBE_UNUSED= \
                          OIIO_NODISCARD:= \
-                         OIIO_DEPRECATED:=[[deprecated]] \
+                         OIIO_DEPRECATED(x)=[[deprecated]] \
                          OIIO_FORMAT_DEPRECATED:= \
                          OIIO_FORCEINLINE=inline \
                          IMATH_HALF_H_=1 \
                          INCLUDED_IMATHVEC_H=1 \
                          INCLUDED_IMATHMATRIX_H=1 \
+                         OIIO_ENABLE_IF(x)="std::enable_if_t<(x), int> = 0" \
 
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
diff --git a/src/doc/requirements.txt b/src/doc/requirements.txt
index f549e74b04..d81b734a6c 100644
--- a/src/doc/requirements.txt
+++ b/src/doc/requirements.txt
@@ -1,4 +1,4 @@
-sphinx >= 5.0
-breathe == 4.34.0
+sphinx >= 8.0
+breathe == 4.36.0
 sphinx-tabs
 furo==2022.6.21
diff --git a/src/doc/texturesys.rst b/src/doc/texturesys.rst
index 2df7ede5ba..e1cd860b49 100644
--- a/src/doc/texturesys.rst
+++ b/src/doc/texturesys.rst
@@ -178,7 +178,7 @@ structure:
 
 - `int colortransformid` :
    If non-zero, specifies a color transformation to apply to the texels, a
-   handle to a transform retrerieved `TextureSystem::get_colortransform_id()`.
+   handle to a transform retrieved `TextureSystem::get_colortransform_id()`.
 
 
 
diff --git a/src/include/OpenImageIO/image_span.h b/src/include/OpenImageIO/image_span.h
index 374b37c704..8381821626 100644
--- a/src/include/OpenImageIO/image_span.h
+++ b/src/include/OpenImageIO/image_span.h
@@ -98,7 +98,7 @@ template<typename T, size_t Rank = 4> class image_span {
     // clang-format off
     /* clang_format gets confused by this */
 
-    /// Copy constructor from image_span<T> to image_span<const T>.
+    /// Copy constructor from `image_span<T>` to `image_span<const T>`.
     template<typename U, size_t R,
              OIIO_ENABLE_IF((std::is_same_v<std::remove_const_t<T>, U>)
                             && std::is_const_v<T> && !std::is_const_v<U>
@@ -112,7 +112,7 @@ template<typename T, size_t Rank = 4> class image_span {
     }
     // clang-format on
 
-    /// Construct from span<T> and dimensions, assume contiguous strides.
+    /// Construct from `span<T>` and dimensions, assume contiguous strides.
     image_span(span<T> data, uint32_t nchannels, uint32_t width,
                uint32_t height, uint32_t depth = 1)
         : image_span(data.data(), nchannels, width, height, depth)
@@ -126,7 +126,7 @@ template<typename T, size_t Rank = 4> class image_span {
     /// same strided data as the operand.
     image_span& operator=(const image_span& copy) = default;
 
-    /// image_span(x,y,z) returns a strided_ptr<T,1> for the pixel (x,y,z).
+    /// image_span(x,y,z) returns a `strided_ptr<T,1>` for the pixel (x,y,z).
     /// The z can be omitted for 2D images.  Note that the resulting
     /// strided_ptr can then have individual channels accessed with
     /// operator[]. This particular strided pointer has stride multiplier 1,
@@ -212,8 +212,8 @@ template<typename T, size_t Rank = 4> class image_span {
                                            ystride(), zstride(), m_chansize);
     }
 
-    /// Convert an image_span<T> to an image_span<std::byte> representing the
-    /// same sized and strided memory pattern represented un-typed memory.
+    /// Convert an `image_span<T>` to an image_span<std::byte> representing
+    /// the same sized and strided memory pattern represented un-typed memory.
     /// Note that this will not work (be a compiler error) if T a const type.
     image_span<std::byte> as_writable_bytes_image_span() const noexcept
     {
diff --git a/src/include/OpenImageIO/span.h b/src/include/OpenImageIO/span.h
index f0c925fa17..e7a3a432bc 100644
--- a/src/include/OpenImageIO/span.h
+++ b/src/include/OpenImageIO/span.h
@@ -95,6 +95,7 @@ class span {
     /// Copy constructor (copies the span pointer and length, NOT the data).
     constexpr span (const span &copy) noexcept = default;
 
+#ifndef OIIO_DOXYGEN  /* this declaration confuses doxygen */
     /// Copy constructor from a different extent (copies the span pointer and
     /// length, NOT the data). This allows for construction of `span<const T>`
     /// from `span<T>`, and for converting fixed extent to dynamic extent.
@@ -104,6 +105,7 @@ class span {
                              && (extent == dynamic_extent || extent == N))>
     constexpr span (const span<U,N> &copy) noexcept
         : m_data(copy.data()), m_size(copy.size()) { }
+#endif
 
     /// Construct from T* and length.
     constexpr span (pointer data, size_type size) noexcept