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 <[email protected]>

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:
 

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

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" ]
 

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 ()