docs: Convert examples within the imagebufalgo chapter.

- Update the run.py scripts to use the OIIO_TESTSUITE_ROOT environment variable instead of a relative path to fetch common images, to ensure tests can be run using ctest; - Convert C++ and Python examples into tests within the "docs-examples" testsuites.
AcademySoftwareFoundation · Oct 12, 2023 · dc7bccb · dc7bccb
1 parent 94fc8f8
commit dc7bccb
Show file tree

Hide file tree

Showing 7 changed files with 41 additions and 18 deletions.
diff --git a/src/doc/imagebufalgo.rst b/src/doc/imagebufalgo.rst
@@ -38,23 +38,19 @@ Most ImageBufAlgo functions that produce image data come in two forms:
    error, the result image returned can have any error conditions checked with
    `has_error()` and `geterror()`.
 
-   .. tabs::
-
-      .. code-tab:: c++
+.. tabs::
 
-          // Method 1: Return an image result
-          ImageBuf dst = ImageBufAlgo::over (fg, bg);
-          if (dst.has_error())
-              std::cout << "error: " << dst.geterror() << "\n";
+   .. tab:: C++
+         .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp
+          :language: c++
+          :start-after: BEGIN-imagebufalgo-output-error1
+          :end-before: END-imagebufalgo-output-error1
 
-      .. code-tab:: py
-
-          # Method 1: Return an image result
-          fg = ImageBuf("fg.exr")
-          bg = ImageBuf("bg.exr")
-          dst = ImageBufAlgo.over (fg, bg)
-          if dst.has_error() :
-              print("error:", dst.geterror())
+   .. tab:: Python
+      .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
+          :language: py
+          :start-after: BEGIN-imagebufalgo-output-error1
+          :end-before: END-imagebufalgo-output-error1
 
 
 2. Pass a destination ImageBuf reference as the first parameter.
@@ -1075,7 +1071,7 @@ Shuffling channels
 
     .. tabs::
 
-       .. code-tab:: c++
+       .. code-tab:: c++`
 
           // Resize the image to 640x480, using the default filter
           ImageBuf Src ("tahoe.exr");

diff --git a/testsuite/docs-examples-cpp/ref/out.txt b/testsuite/docs-examples-cpp/ref/out.txt
@@ -1,3 +1,4 @@
+error: Uninitialized input image
 cshift.exr           :  256 x  256, 4 channel, half openexr
     SHA-1: 000F95FDC44D4DBDA8B4041C2506149C7AE28ACA
 Comparing "simple.tif" and "ref/simple.tif"

diff --git a/testsuite/docs-examples-cpp/run.py b/testsuite/docs-examples-cpp/run.py
@@ -11,7 +11,7 @@
     prefix = "./build/"
 
 # Prep:
-command += run_app("cmake -E copy ../common/grid-small.exr grid.exr")
+command += run_app("cmake -E copy ${OIIO_TESTSUITE_ROOT}/common/grid-small.exr grid.exr")
 
 # Build
 command += run_app("cmake -S " + test_source_dir + " -B build -DCMAKE_BUILD_TYPE=Release >> build.txt 2>&1", silent=True)

diff --git a/testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp b/testsuite/docs-examples-cpp/src/docs-examples-imagebufalgo.cpp
@@ -35,6 +35,18 @@ void example1()
 
 // Section: ImageBufAlgo common principles
 
+void example_output_error1()
+{
+    ImageBuf fg, bg;
+
+    // BEGIN-imagebufalgo-output-error1
+    // Method 1: Return an image result
+    ImageBuf dst = ImageBufAlgo::over (fg, bg);
+    if (dst.has_error())
+        std::cout << "error: " << dst.geterror() << "\n";
+    // END-imagebufalgo-output-error1
+}
+
 
 // Section: Pattern Generation
 
@@ -83,6 +95,7 @@ int main(int /*argc*/, char** /*argv*/)
     example1();
 
     // Section: ImageBufAlgo common principles
+    example_output_error1();
 
     // Section: Pattern Generation
 

diff --git a/testsuite/docs-examples-python/ref/out.txt b/testsuite/docs-examples-python/ref/out.txt
@@ -1,3 +1,4 @@
+error: Uninitialized input image
 cshift.exr           :  256 x  256, 4 channel, half openexr
     SHA-1: 000F95FDC44D4DBDA8B4041C2506149C7AE28ACA
 Comparing "simple.tif" and "ref/simple.tif"

diff --git a/testsuite/docs-examples-python/run.py b/testsuite/docs-examples-python/run.py
@@ -6,7 +6,7 @@
 
 
 # Prep:
-command += run_app("cmake -E copy ../common/grid-small.exr grid.exr")
+command += run_app("cmake -E copy ${OIIO_TESTSUITE_ROOT}/common/grid-small.exr grid.exr")
 
 # Run the examples for each chapter
 for chapter in [ "imageioapi", "imageoutput", "imageinput", "writingplugins",

diff --git a/testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py b/testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
@@ -40,6 +40,17 @@ def example1() :
 
 # Section: ImageBufAlgo common principles
 
+def example_output_error1():
+    fg = ImageBuf()
+    bg = ImageBuf()
+
+    # BEGIN-imagebufalgo-output-error1
+    # Method 1: Return an image result
+    dst = ImageBufAlgo.over(fg, bg)
+    if dst.has_error:
+        print("error:", dst.geterror())
+    # END-imagebufalgo-output-error1
+
 
 # Section: Pattern Generation
 
@@ -85,6 +96,7 @@ def example_circular_shift() :
     example1()
 
     # Section: ImageBufAlgo common principles
+    example_output_error1()
 
     # Section: Pattern Generation