Docs: for rtd, upgrade sphinx/breathe versions, use furo theme

src/doc/conf.py

@@ -89,7 +89,8 @@
 #
 #html_theme = 'alabaster'
 #html_theme = 'astropy-sphinx-theme'
-html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinx_rtd_theme'
+html_theme = 'furo'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

src/doc/imagebufalgo.rst

@@ -850,8 +850,8 @@ Shuffling channels
        .. code-tab:: py
 
           # Paste fg.exr on top of bg.exr, offset by (100,100)
-          Bg ImageBuf("bg.exr")
-          Fg ImageBuf("fg.exr")
+          Bg = ImageBuf("bg.exr")
+          Fg = ImageBuf("fg.exr")
           ImageBufAlgo.paste (Bg, 100, 100, 0, 0, Fg)
 
        .. code-tab:: bash oiiotool

src/doc/imageioapi.rst

@@ -69,7 +69,11 @@ and the documentation of individual ImageIO plugins for details).
 Non-owning string views: ``string_view``
 ==========================================
 
-.. doxygenclass:: OIIO::string_view
+.. cpp:type:: using string_view = basic_string_view<char>;
+
+    `string_view` is a synonym for a non-mutable `string_view<char>`.
+
+.. doxygenclass:: OIIO::basic_string_view
     :members:
 
 |

src/doc/oiiotool.rst

@@ -246,7 +246,7 @@ The usual programming constructs are supported:
 
 * Conditionals : `--if` *condition* `--then` *commands...* `--else` *commands...* `--endif`
 
-* General looping: `--while` *condition* *commands...*
+* General looping: `--while` *condition* *commands...* `--endwhile`
 
 * Iteration : `--for` *variable* *range* *commands...* `--endfor`
 
@@ -2369,8 +2369,8 @@ current top image.
 
 
 .. option:: --sub
-            -- subc <value>
-            -- subc <value0,value1,value2...>
+            --subc <value>
+            --subc <value0,value1,value2...>
 
     Replace the *two* top images with a new image that is the pixel-by-pixel
     difference between the first and second images (`--sub`), or subtract a
@@ -2388,8 +2388,8 @@ current top image.
 
 
 .. option:: --mul
-            -- mulc <value>
-            -- mulc <value0,value1,value2...>
+            --mulc <value>
+            --mulc <value0,value1,value2...>
 
     Replace the *two* top images with a new image that is the pixel-by-pixel
     multiplicative product of those images (`--mul`), or multiply all pixels
@@ -2419,8 +2419,8 @@ current top image.
 
 
 .. option:: --div
-            -- divc <value>
-            -- divc <value0,value1,value2...>
+            --divc <value>
+            --divc <value0,value1,value2...>
 
     Replace the *two* top images with a new image that is the
     pixel-by-pixel, channel-by-channel result of the first image divided by

src/doc/requirements.txt

@@ -1,3 +1,4 @@
-sphinx >= 3.0
-breathe == 4.27.0
+sphinx >= 5.0
+breathe == 4.34.0
 sphinx-tabs
+furo==2022.6.21

src/include/OpenImageIO/span.h

@@ -42,14 +42,14 @@ OIIO_INLINE_CONSTEXPR oiio_span_size_type dynamic_extent = -1;
 
 
 
-/// span<T> is a non-owning, non-copying, non-allocating reference to a
+/// `span<T>` is a non-owning, non-copying, non-allocating reference to a
 /// contiguous array of T objects known length. A 'span` encapsulates both a
 /// pointer and a length, and thus is a safer way of passing pointers around
 /// (because the function called knows how long the array is). A function
 /// that might ordinarily take a `T*` and a length could instead just take a
 /// `span<T>`.
 ///
-/// `A span<T>` is mutable (the values in the array may be modified).  A
+/// A `span<T>` is mutable (the values in the array may be modified).  A
 /// non-mutable (i.e., read-only) reference would be `span<const T>`. Thus,
 /// a function that might ordinarily take a `const T*` and a length could
 /// instead take a `span<const T>`.

src/include/OpenImageIO/string_view.h

@@ -40,6 +40,8 @@ OIIO_NAMESPACE_BEGIN
 /// and a length. This is analogous to C++17 std::string_view, but supports
 /// C++14.
 ///
+/// Note: `string_view` is an alias for `basic_string_view<char>`.
+///
 /// A function that takes a string input (but does not need to alter the
 /// string in place) may use a string_view parameter and accept input that
 /// is any of char* (C string), string literal (constant char array), a