[Docs] Add hybrid plugin system notebook

Part of OpenAssetIO/OpenAssetIO#1202. Add a Jupyter Notebook
illustrating the design and usage of the hybrid plugin system.

Bump the minimum versions of OpenAssetIO and BAL in `requirements.txt`
to support the required features for the notebook to run.

Use a custom hybrid plugin created especially for the notebook, rather
than attempting to sellotape existing managers together (e.g. BAL and
SimpleCppManager). This allows the notebook to avoid potentially
confusing readers with misleading text about configuring two completely
independent plugins to work together. For the custom plugin sources, use
linter config lifted from the main OpenAssetIO repo, with little
modification.

Signed-off-by: David Feltell <[email protected]>

.github/build_openassetio/action.yml

@@ -7,6 +7,10 @@
 
 name: Build OpenAssetIO
 description: Builds OpenAssetIO and publishes an artifact
+inputs:
+  install-prefix:
+    description: Where to install OpenAssetIO once built
+    required: true
 runs:
   using: "composite"
   steps:
@@ -20,13 +24,6 @@ runs:
     - name: Build OpenAssetIO
       shell: bash
       run: |
-        cd openassetio-checkout
-        mkdir build
-        cmake -G Ninja -S . -B build
-        cmake --build build
-        cmake --install build
-    - uses: actions/upload-artifact@v3
-      with:
-        name: OpenAssetIO Build
-        path: openassetio-checkout/build/dist
-        retention-days: 1
+        cmake -G Ninja -S openassetio-checkout -B openassetio-checkout/build 
+        cmake --build openassetio-checkout/build
+        cmake --install openassetio-checkout/build --prefix ${{ inputs.install-prefix }}

.github/workflows/examples.yml

@@ -18,6 +18,9 @@ jobs:
       matrix:
         os: ["windows-2022", "ubuntu-22.04", "macos-13"]
         python: ["3.10", "3.11"]
+    defaults:
+      run:
+        shell: bash
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
@@ -28,4 +31,55 @@ jobs:
           python -m pip install .
           python -m pip install -r examples/resources/requirements.txt
       - name: Test Notebooks
-        run: jupyter nbconvert --to html --execute examples/*.ipynb
+        # Execute all the notebooks apart from the Hybrid Plugin System,
+        # which requires a build of SimpleCppManager
+        run: >
+          find examples -maxdepth 1 -name "*.ipynb"
+          ! -name "hybrid_plugin_system.ipynb"
+          -exec jupyter nbconvert --to html --execute {} \;
+
+  test-cpp-notebooks:
+    # A special job just for the Hybrid Plugin System because it needs a
+    # C++ build.
+    name: Test Hybrid Plugin System notebook
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/openassetio/openassetio-build
+    env:
+      SIMPLEHYBRIDMANAGER_SUBDIR: examples/resources/hybrid_plugin_system/SimpleHybridManager
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Dependencies
+        run: |
+          python -m pip install .
+          python -m pip install -r examples/resources/requirements.txt
+          python -m pip install openassetio-traitgen
+
+      - name: Build/install OpenAssetIO
+        uses: ./.github/build_openassetio
+        with:
+          install-prefix: ${{ env.SIMPLEHYBRIDMANAGER_SUBDIR }}/dependencies
+
+      - name: Build/install MediaCreation
+        run: |
+          cmake -S . -B build -G Ninja
+          cmake --build build
+          cmake --install build --prefix $SIMPLEHYBRIDMANAGER_SUBDIR/dependencies
+
+      - name: Build/install SimpleHybridManager
+        run: |
+          cmake -S src -B build -G Ninja
+          cmake --build build
+          cmake --install build --prefix plugin
+        env:
+          CMAKE_PREFIX_PATH: dependencies
+        # Since we're in a Docker container, `github.workspace` doesn't
+        # give the correct location, except, for some reason, when used
+        # in a `working-directory` option. See
+        # https://github.com/actions/runner/issues/2058#issuecomment-1541828550
+        working-directory: ${{ github.workspace }}/${{ env.SIMPLEHYBRIDMANAGER_SUBDIR }}
+
+      - name: Test notebook
+        run: jupyter nbconvert --to html --execute examples/hybrid_plugin_system.ipynb
+
+

.github/workflows/test.yml

@@ -11,16 +11,6 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build-openassetio:
-    name: Build OpenAssetIO
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/openassetio/openassetio-build
-    steps:
-      - uses: actions/checkout@v3
-      - name: Build
-        uses: ./.github/build_openassetio
-
   test-python:
     name: "${{ matrix.os }} python-${{ matrix.python }}"
     runs-on: ${{ matrix.os }}
@@ -43,25 +33,22 @@ jobs:
   test-cpp:
     name: Test Cpp
     runs-on: ubuntu-latest
-    needs: build-openassetio
     container:
-      image: aswf/ci-base:2024
+      image: ghcr.io/openassetio/openassetio-build
     steps:
       - uses: actions/checkout@v3
 
+      - name: Build OpenAssetIO
+        uses: ./.github/build_openassetio
+        with:
+          install-prefix: openassetio
+
       - name: Install Traitgen
         run: python -m pip install openassetio-traitgen==1.0.0a10
 
-      - name: Get OpenAssetIO
-        uses: actions/download-artifact@v3
-        with:
-          name: OpenAssetIO Build
-          path: ./openassetio-build
-
       - name: Configure CMake build
-        run: >
-          cmake -S . -DCMAKE_PREFIX_PATH=`pwd`/openassetio-build -B build -G Ninja
-          --preset test
+        run: |
+          cmake -S . -DCMAKE_PREFIX_PATH=$(pwd)/openassetio -B build -G Ninja --preset test
 
       - name: Build tests
         run: cmake --build build