From fdee1157972b96f86e11afe8c8693e691eced76b Mon Sep 17 00:00:00 2001
From: Larry Gritz <lg@larrygritz.com>
Date: Thu, 7 Sep 2023 09:13:35 -0700
Subject: [PATCH] WIP - Prototype docs examples doubling as tests

New theory of code examples in the docs: every one should live in the
testsuite somewhere, and merely be included by reference in the docs.
This ensures that every code example works, stays current with the
evolution of the APIs, and never breaks. It also beefs up our test
cases for more thorough code overage in the testsuite.

I've done this with just one example here, but hopefully it serves as
an example for others to -- bit by bit -- convert all the other code
examples in the docs into tests in a similar manner.

Doing this for any one example is a perfect "good first issue," since
it's bite sized and can easily be done in a day, it doesn't require
any knowledge of deep OIIO internals, and in the process it also
teaches you something about how both the docs and the testsuite are
set up.

Signed-off-by: Larry Gritz <lg@larrygritz.com>
---
 src/doc/imageoutput.rst                       | 24 +++++--------------
 testsuite/python-imageoutput/ref/out.txt      |  2 ++
 testsuite/python-imageoutput/run.py           |  5 ++--
 .../src/docs_simplewrite.py                   | 15 ++++++++++++
 4 files changed, 26 insertions(+), 20 deletions(-)
 create mode 100644 testsuite/python-imageoutput/src/docs_simplewrite.py

diff --git a/src/doc/imageoutput.rst b/src/doc/imageoutput.rst
index 78446208e4..53085f0e9d 100644
--- a/src/doc/imageoutput.rst
+++ b/src/doc/imageoutput.rst
@@ -24,10 +24,10 @@ to a file:
        using namespace OIIO;
        ...
 
-       const char *filename = "foo.jpg";
+       const char *filename = "simple.tif";
        const int xres = 640, yres = 480;
        const int channels = 3;  // RGB
-       unsigned char pixels[xres * yres * channels];
+       unsigned char pixels[xres * yres * channels] = { 0 };
 
        std::unique_ptr<ImageOutput> out = ImageOutput::create (filename);
        if (! out)
@@ -37,23 +37,11 @@ to a file:
        out->write_image (TypeDesc::UINT8, pixels);
        out->close ();
 
-    .. code-tab:: py
+    .. tab::
+
+        .. include:: ../../testsuite/python-imageoutput/src/docs_simplewrite.py
+            :code: py
 
-       import OpenImageIO as oiio
-       import numpy as np
-
-       filename = "foo.jpg"
-       xres = 640
-       yres = 480
-       channels = 3  # RGB
-       pixels = np.zeros((yres, xres, channels), dtype=np.uint8)
-
-       out = oiio.ImageOutput.create (filename)
-       if out:
-           spec = oiio.ImageSpec(xres, yres, channels, 'uint8')
-           out.open (filename, spec)
-           out.write_image (pixels)
-           out.close ()
 
 This little bit of code does a surprising amount of useful work:
 
diff --git a/testsuite/python-imageoutput/ref/out.txt b/testsuite/python-imageoutput/ref/out.txt
index 09ca440aeb..b8fc155e09 100644
--- a/testsuite/python-imageoutput/ref/out.txt
+++ b/testsuite/python-imageoutput/ref/out.txt
@@ -23,3 +23,5 @@ Comparing "grid-half.exr" and "../common/grid.tif"
 PASS
 Comparing "multipart.exr" and "ref/multipart.exr"
 PASS
+Comparing "simple.tif" and "ref/simple.tif"
+PASS
diff --git a/testsuite/python-imageoutput/run.py b/testsuite/python-imageoutput/run.py
index cfa7e01610..67781a4c43 100755
--- a/testsuite/python-imageoutput/run.py
+++ b/testsuite/python-imageoutput/run.py
@@ -10,7 +10,8 @@
 command += oiio_app("iconvert") + "../common/grid.tif --tile 64 64 tiled.tif > out.txt ;" 
 
 # Run the script 
-command += pythonbin + " src/test_imageoutput.py > out.txt ;"
+command += pythonbin + " src/test_imageoutput.py >> out.txt ;"
+command += pythonbin + " src/docs_simplewrite.py >> out.txt ;"
 
 # compare the outputs -- these are custom because they compare to grid.tif
 files = [ "grid-image.tif", "grid-scanline.tif", "grid-scanlines.tif",
@@ -19,5 +20,5 @@
     command += (oiio_app("idiff") + " -fail 0.001 -warn 0.001 "
                 + f + " ../common/grid.tif >> out.txt ;")
 
-outputs = [ "multipart.exr", "out.txt" ]
+outputs = [ "multipart.exr", "simple.tif", "out.txt" ]
 
diff --git a/testsuite/python-imageoutput/src/docs_simplewrite.py b/testsuite/python-imageoutput/src/docs_simplewrite.py
new file mode 100644
index 0000000000..3f5b20a0d4
--- /dev/null
+++ b/testsuite/python-imageoutput/src/docs_simplewrite.py
@@ -0,0 +1,15 @@
+import OpenImageIO as oiio
+import numpy as np
+
+filename = "simple.tif"
+xres = 640
+yres = 480
+channels = 3  # RGB
+pixels = np.zeros((yres, xres, channels), dtype=np.uint8)
+
+out = oiio.ImageOutput.create (filename)
+if out:
+    spec = oiio.ImageSpec(xres, yres, channels, 'uint8')
+    out.open (filename, spec)
+    out.write_image (pixels)
+    out.close ()