Build docs in CI, and rename DOCS CMake config variable to BUILD_DOCS (…

…AcademySoftwareFoundation#1339) * Add docs to CI Signed-off-by: Cary Phillips <cary@ilm.com> * yum scripts Signed-off-by: Cary Phillips <cary@ilm.com> --------- Signed-off-by: Cary Phillips <cary@ilm.com>
cary-ilm · Mar 3, 2023 · 055acc1 · 055acc1
1 parent d93a5ee
commit 055acc1
Show file tree

Hide file tree

Showing 5 changed files with 45 additions and 4 deletions.
diff --git a/.github/workflows/ci_workflow.yml b/.github/workflows/ci_workflow.yml
@@ -47,7 +47,8 @@ jobs:
        C++${{ matrix.cxx-standard }},
        config=${{ matrix.build-type }},
        shared=${{ matrix.build-shared }},
-       threads=${{ matrix.threads-enabled }}>'
+       threads=${{ matrix.threads-enabled }},
+       docs=${{ matrix.build-docs }}>'
     # GH-hosted VM. The build runs in CentOS 7 'container' defined below.
     runs-on: ubuntu-latest
     container:
@@ -73,6 +74,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'ON'
             exclude-tests:
 
           # Shared, Release, Threads OFF
@@ -86,6 +88,7 @@ jobs:
             label: 
             threads-enabled: 'OFF'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Shared, Debug
@@ -99,6 +102,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Release
@@ -112,6 +116,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Debug
@@ -125,6 +130,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # -------------------------------------------------------------------
@@ -141,6 +147,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Debug
@@ -154,6 +161,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Release
@@ -167,6 +175,7 @@ jobs:
             label: 
             threads-enabled: 'ON'
             vfx-cy: 2022
+            build-docs: 'OFF'
             exclude-tests:
 
           # Static, Debug
@@ -179,6 +188,7 @@ jobs:
             compiler-desc: clang10
             label: 
             threads-enabled: 'ON'
+            build-docs: 'OFF'
             vfx-cy: 2022
             exclude-tests:
 
@@ -195,6 +205,7 @@ jobs:
             compiler-desc: gcc9.3.1
             label: 
             threads-enabled: 'ON'
+            build-docs: 'OFF'
             vfx-cy: 2021
             exclude-tests:
 
@@ -211,6 +222,7 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 
             threads-enabled: 'ON'
+            build-docs: 'OFF'
             vfx-cy: 2020
             exclude-tests:
 
@@ -227,6 +239,7 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 
             threads-enabled: 'ON'
+            build-docs: 'OFF'
             vfx-cy: 2019
             exclude-tests: 
 
@@ -243,6 +256,7 @@ jobs:
             compiler-desc: gcc6.3.1
             label: 'Legacy '
             threads-enabled: 'ON'
+            build-docs: 'OFF'
             vfx-cy: 2019
             exclude-tests:
 
@@ -257,6 +271,9 @@ 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 .. \
@@ -266,6 +283,7 @@ 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 }}

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -122,8 +122,8 @@ if(NOT OPENEXR_IS_SUBPROJECT)
   include(cmake/clang-format.cmake)
 endif()
 
-option(DOCS "Set ON to build html documentation")
-if (DOCS AND NOT OPENEXR_IS_SUBPROJECT)
+option(BUILD_DOCS "Set ON to build html documentation")
+if (BUILD_DOCS AND NOT OPENEXR_IS_SUBPROJECT)
   option(INSTALL_DOCS "Set ON to install html documentation" ON)
   add_subdirectory(docs)
 endif()

diff --git a/docs/install.rst b/docs/install.rst
@@ -194,7 +194,7 @@ The OpenEXR technical documentation at `https://openexr.readthedocs.io
 extracted from header comments by `Doxygen <https://www.doxygen.nl>`_.
 
 To build the documentation locally from the source headers and
-``.rst`` files, set the CMake option ``DOCS=ON``. This adds
+``.rst`` files, set the CMake option ``BUILD_DOCS=ON``. This adds
 ``Doxygen`` and ``Sphinx`` CMake targets and enables building the docs
 by default.  generation is off by default.
 

diff --git a/share/ci/scripts/linux/yum/install_docs_env.sh b/share/ci/scripts/linux/yum/install_docs_env.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenColorIO Project.
+
+set -ex
+
+HERE=$(dirname $0)
+
+bash $HERE/install_doxygen.sh latest
+pip3 install -r $HERE/../../../../../docs/requirements.txt
diff --git a/share/ci/scripts/linux/yum/install_doxygen.sh b/share/ci/scripts/linux/yum/install_doxygen.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenColorIO Project.
+
+set -ex
+
+DOXYGEN_VERSION="$1"
+
+if [ "$DOXYGEN_VERSION" == "latest" ]; then
+    yum install -y doxygen
+else
+    yum install -y doxygen-${DOXYGEN_VERSION}
+fi