Test Images page for website

.github/workflows/ci_workflow.yml

@@ -47,8 +47,7 @@ jobs:
        C++${{ matrix.cxx-standard }},
        config=${{ matrix.build-type }},
        shared=${{ matrix.build-shared }},
-       threads=${{ matrix.threads-enabled }},
-       docs=${{ matrix.build-docs }}>'
+       threads=${{ matrix.threads-enabled }}>'
     # GH-hosted VM. The build runs in CentOS 7 'container' defined below.
     runs-on: ubuntu-latest
     container:
@@ -74,7 +73,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'ON'
             exclude-tests:
 
           # Shared, Release, Threads OFF
@@ -88,7 +86,6 @@ jobs:
             label: 
             threads-enabled: 'OFF'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Shared, Debug
@@ -102,7 +99,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Release
@@ -116,7 +112,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Debug
@@ -130,7 +125,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # -------------------------------------------------------------------
@@ -147,7 +141,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Debug
@@ -161,7 +154,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Release
@@ -175,7 +167,6 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
-            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Debug
@@ -188,7 +179,6 @@ jobs:
             compiler-desc: clang10
             label: 
             threads-enabled: 'ON'
-            build-docs: 'OFF'
             vfx-cy: 2022
             exclude-tests:
 
@@ -205,7 +195,6 @@ jobs:
             compiler-desc: gcc9.3.1
             label: 
             threads-enabled: 'ON'
-            build-docs: 'OFF'
             vfx-cy: 2021
             exclude-tests:
 
@@ -222,7 +211,6 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 
             threads-enabled: 'ON'
-            build-docs: 'OFF'
             vfx-cy: 2020
             exclude-tests:
 
@@ -239,7 +227,6 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 
             threads-enabled: 'ON'
-            build-docs: 'OFF'
             vfx-cy: 2019
             exclude-tests: 
 
@@ -256,7 +243,6 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 'Legacy '
             threads-enabled: 'ON'
-            build-docs: 'OFF'
             vfx-cy: 2019
             exclude-tests:
 
@@ -271,9 +257,6 @@ jobs:
           mkdir _install
           mkdir _build
           mkdir _examples
-      - name: Install docs env
-        run: share/ci/scripts/linux/yum/install_docs_env.sh
-        if: matrix.build-docs == 'ON'
       - name: Configure
         run: |
           cmake .. \
@@ -283,7 +266,6 @@ jobs:
                 -DCMAKE_CXX_FLAGS=${{ matrix.cxx-flags }} \
                 -DCMAKE_VERBOSE_MAKEFILE:BOOL='OFF' \
                 -DBUILD_SHARED_LIBS=${{ matrix.build-shared }} \
-                -DBUILD_DOCS=${{ matrix.build-docs }} \
                 -DOPENEXR_BUILD_TOOLS='ON' \
                 -DOPENEXR_RUN_FUZZ_TESTS='OFF' \
                 -DOPENEXR_ENABLE_THREADING=${{ matrix.threads-enabled }}
@@ -332,8 +314,7 @@ jobs:
        C++${{ matrix.cxx-standard }},
        config=${{ matrix.build-type }},
        shared=${{ matrix.build-shared }},
-       cxx=${{ matrix.cxx-standard }},
-       docs=${{ matrix.build-docs }}>'
+       cxx=${{ matrix.cxx-standard }}>'
     runs-on: macos-${{ matrix.osver }}
     strategy:
       matrix:
@@ -346,7 +327,6 @@ jobs:
           - build: 1
             build-type: Release
             build-shared: 'ON'
-            build-docs: 'OFF'
             compiler-desc: AppleClang11.0
             cxx-standard: 17
             osver: 10.15
@@ -356,7 +336,6 @@ jobs:
           - build: 2
             build-type: Release
             build-shared: 'OFF'
-            build-docs: 'OFF'
             compiler-desc: AppleClang11.0
             cxx-standard: 17
             osver: 10.15
@@ -366,7 +345,6 @@ jobs:
           - build: 3
             build-type: Debug
             build-shared: 'ON'
-            build-docs: 'OFF'
             compiler-desc: AppleClang11.0
             cxx-standard: 17
             osver: 10.15
@@ -430,8 +408,7 @@ jobs:
       <${{ matrix.compiler-desc }},
        config=${{ matrix.build-type }}, 
        shared=${{ matrix.build-shared }}, 
-       cxx=${{ matrix.cxx-standard }}, 
-       docs=${{ matrix.build-docs }}>'
+       cxx=${{ matrix.cxx-standard }}>'
     runs-on: windows-${{ matrix.osver }}
     strategy:
       matrix:
@@ -444,7 +421,6 @@ jobs:
           - build: 1
             build-type: Release
             build-shared: 'ON'
-            build-docs: 'OFF'
             compiler-desc: msvc16.11
             cxx-standard: 17
             vfx-cy: 2021
@@ -455,7 +431,6 @@ jobs:
           - build: 2
             build-type: Release
             build-shared: 'OFF'
-            build-docs: 'OFF'
             compiler-desc: msvc16.11
             cxx-standard: 17
             vfx-cy: 2021
@@ -469,7 +444,6 @@ jobs:
           - build: 3
             build-type: Release
             build-shared: 'ON'
-            build-docs: 'OFF'
             compiler-desc: msvc17.1
             cxx-standard: 17
             vfx-cy: 2021
@@ -480,7 +454,6 @@ jobs:
           - build: 4
             build-type: Release
             build-shared: 'OFF'
-            build-docs: 'OFF'
             compiler-desc: msvc17.1
             cxx-standard: 17
             vfx-cy: 2021
@@ -547,3 +520,37 @@ jobs:
                 -VV
         shell: bash
         working-directory: _build
+
+  Docs:
+
+    # Build the documentation, using a process that mimics the readthedoc build.
+    #
+    # Note that this job does not actually build OpenEXR libraries or
+    # programs, it just runs doxygen, sphinx, and the
+    # docs/script/test_images.py script to generate the "Test Images"
+    # page.
+
+    name: 'Docs'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Create build directory
+        run: mkdir _build
+      - name: Install doxygen & imagemagick
+        # Need imagemagick for convert, to convert "Test Image" exrs to jpgs
+        # Need openexr for exrheader
+        run: sudo apt-get install -y doxygen imagemagick openexr
+      - name: Install sphinx requirements
+        run: pip3 install -r docs/requirements.txt
+      - name: Configure
+        run: cmake .. -DBUILD_DOCS='ON'
+        working-directory: _build
+      - name: Build
+        run: |
+          cmake --build . \
+                --target docs \
+                --config Release
+        working-directory: _build
+

.gitignore

@@ -49,4 +49,5 @@ build/
 build-win/
 build-nuget/
 *~
-.vscode
+.vscode
+docs/_test_images/

.readthedocs.yml

@@ -0,0 +1,25 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.9"
+  apt_packages:
+    - wget        # for test images
+    - imagemagick # for convert, for test images
+    - openexr     # for exrheader, for test images
+  jobs:
+    pre_build:
+       - python docs/scripts/test_images.py 
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/CMakeLists.txt

@@ -21,6 +21,14 @@ set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
 set(SPHINX_OPTS "-W" CACHE STRING "Sphinx build options")
 
+set(OPENEXR_TEST_IMAGE_REPO "https://raw.githubusercontent.com/AcademySoftwareFoundation/openexr-images" 
+    CACHE STRING "Repo for test images")
+set(OPENEXR_TEST_IMAGE_TAG "main" 
+    CACHE STRING "Tag for test image repo")
+
+set(TEST_IMAGE_INDEX_FILE ${PROJECT_SOURCE_DIR}/docs/_test_images/index.rst)
+set(TEST_IMAGE_PY_FILE ${PROJECT_SOURCE_DIR}/docs/scripts/test_images.py)
+set(TEST_IMAGE_INPUT_FILE ${PROJECT_SOURCE_DIR}/docs/test_images.txt)
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
 file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
@@ -31,18 +39,33 @@ add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
                    COMMENT "Running doxygen"
                    VERBATIM)
 
+add_custom_command(OUTPUT ${TEST_IMAGE_INDEX_FILE}
+                   # run the test_images.py script with the PATH set
+                   # to include the build's bin directory, to pick up
+                   # the local bin/exrheader executable
+                   COMMAND ${CMAKE_COMMAND} -E env "PATH=${CMAKE_CURRENT_BINARY_DIR}/../bin:$ENV{PATH}"
+                   ${Python3_EXECUTABLE} ${TEST_IMAGE_PY_FILE} ${OPENEXR_TEST_IMAGE_REPO} ${OPENEXR_TEST_IMAGE_TAG} 
+                   WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+                   DEPENDS
+                   ${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE}
+                   COMMENT "Generating test image pages"
+                   VERBATIM)
+
 add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
                    COMMAND 
                      ${SPHINX_EXECUTABLE} -b html ${SPHINX_OPTS}
                      # Tell Breathe where to find the Doxygen output
                      -Dbreathe_projects.OpenEXR=${DOXYGEN_OUTPUT_DIR}/xml
                    ${SPHINX_SOURCE} ${SPHINX_BUILD}
                    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-                   DEPENDS ${DOXYGEN_INDEX_FILE}
-                   MAIN_DEPENDENCY conf.py
+                   DEPENDS ${DOXYGEN_INDEX_FILE} ${TEST_IMAGE_INDEX_FILE} ${TEST_IMAGE_PY_FILE} ${TEST_IMAGE_INPUT_FILE} 
+                   MAIN_DEPENDENCY ${SPHINX_CONF_PY_FILE}
                    COMMENT "Generating documentation with Sphinx")
 
-add_custom_target(docs ALL DEPENDS ${SPHINX_INDEX_FILE} ${DOXYGEN_INDEX_FILE})
+add_custom_target(docs ALL DEPENDS
+                 ${SPHINX_INDEX_FILE}
+                 ${DOXYGEN_INDEX_FILE}
+                 ${TEST_IMAGE_INDEX_FILE})
 
 # Add an install target to install the docs
 if(INSTALL_DOCS)