Test Images page for website (#1372)

This adds a "Test Image" section to the website with a gallery of images from the test image repo https://github.com/AcademySoftwareFoundation/openexr-images, with a page for each image that shows the output of exrheader. Each image is a link to download the .exr file. Preview it here: https://cary-ilm-openexr.readthedocs.io/en/docs-images/index.html It's not perfect, but it's a decent start, feel free to suggest improvements to the layout or content. A few notes: In lieu of setting up a way to view .exr images directly in a browser, I converted the .exr's in openexr-images to .jpg's. They are stored in the openexr-images repo and served to the website directly from github, so the OpenEXR distribution (which holds the website source) doesn't get bloated with extra image data. The download link downloads the source .exr image, not the .jpg. This draft actually serves them from a branch of my fork of the openexr-images repo, but that can get fixed later. The exr2rst.py script generates the rst (and embedded html) from the .exr's (by running exrheader) and the accompanying README's, so it's (relatively) easy to add new images. --------- Major update to this, the .rst and the proxy .jpg’s are now generated automatically, so no need to maintain .jpg’s in the openexr-images repo. The docs/test_images.txt file lists urls for .exr’s and README.rst files that define the contents of the “Test Images” page. The docs/scripts/test_images.py script builds the index page and the per-image pages. It downloads the files via wget, then runs convert (ImageMagick) to generate the proxy .jpg’s, then runs exrheader to generate the tables of attribute values. The script puts the auto-generated .rst files in the docs/_test_images subdirectory. Ideally, these would go in the build directory, but sphinx seems to want all .rst input under a single source root. There's now a separate "Docs" CI job that builds the docs, so I removed all references to docs in the other jobs. It uses Ubuntu to mirror .readthedocs.yml. There's no need for the install_doxygen.sh and install_docs_env.sh scripts, the necessary installations are simple enough to do inline in the CI job. --------- Signed-off-by: Cary Phillips <cary@ilm.com>
AcademySoftwareFoundation · Apr 7, 2023 · 71a7141 · 71a7141
1 parent c6aec02
commit 71a7141
Show file tree

Hide file tree

Showing 9 changed files with 688 additions and 57 deletions.
diff --git a/.github/workflows/ci_workflow.yml b/.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
+
diff --git a/.gitignore b/.gitignore
@@ -49,4 +49,5 @@ build/
 build-win/
 build-nuget/
 *~
-.vscode
+.vscode
+docs/_test_images/
diff --git a/.readthedocs.yml b/.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
diff --git a/docs/CMakeLists.txt b/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)