[Docs] Add Juypyter notebook covering version workflows

Adds a Jupyter notebook that demonstrates the traits and specifications
that can be used to introspect entity versioning information and
relationships.

It includes a CI task that executes and renders the notebook so we can
ensure that the included code works.

We opted not to `!python -m pip install` dependecies in the notebook
itself to avoid polluting the parent Python environment. The included
`examples/resources/requirements.txt` installs the needed
pre-requisites. Opted to share one requirements file for all notebooks
for now to simplify setup.

Signed-off-by: Tom Cowland <tom@foundry.com>

.github/workflows/examples.yml

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2023 The Foundry Visionmongers Ltd
+
+name: Examples
+on:
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test-notebooks:
+    name: "Test Notebooks ${{ matrix.os }} python-${{ matrix.python }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["windows-latest", "ubuntu-latest", "macos-latest"]
+        python: ["3.7", "3.9", "3.10"]
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install Dependencies
+        run: |
+          python -m pip install .
+          python -m pip install -r examples/resources/requirements.txt
+      - name: Test Notebooks
+        run: jupyter nbconvert --to html --execute examples/*.ipynb

.gitignore

@@ -1 +1,2 @@
 *.egg-info
+.ipynb_checkpoints

examples/resources/helpers.py

@@ -0,0 +1,33 @@
+import json
+import os
+
+from IPython.display import display
+from PIL import Image
+from urllib.parse import urlparse, unquote
+
+def print_traits_data(data):
+    """
+    TraitsData objects arent readily convertable to a dict, or printable
+    at present. This is a little helper to aid the display of OpenAssetIO
+    data in the context of a notebook. It prints the traits and their
+    properties using pretty json formatting.
+    """
+    as_dict = {
+        trait_id: {
+            property_key: data.getTraitProperty(trait_id, property_key)
+            for property_key in data.traitPropertyKeys(trait_id)
+        }
+        for trait_id in data.traitSet()
+    }
+    print(json.dumps(as_dict, indent=4, sort_keys=True))
+
+def display_image(url):
+    """
+    Displays an image in the notebook output.
+    """
+    url_parts = urlparse(url)
+    path = unquote(url_parts.path)
+    if os.name == "nt":
+        path = path.lstrip("/")
+    image = Image.open(path)
+    display(image)

examples/resources/requirements.txt

@@ -0,0 +1,5 @@
+jupyter
+openassetio>=v1.0.0b1rev0
+openassetio-manager-bal>=v1.0.0a13
+openassetio-mediacreation
+Pillow

examples/resources/versioning/bal_database.json

@@ -0,0 +1,38 @@
+{
+  "managementPolicy": {
+    "read": {
+      "default": {
+        "openassetio-mediacreation:managementPolicy.Managed": {},
+        "openassetio-mediacreation:content.LocatableContent": {}
+      }
+    },
+  },
+  "entities": {
+    "project_artwork/logos/openassetio": {
+      "versions": [
+        {
+          "traits": {
+            "openassetio-mediacreation:identity.DisplayName": {
+              "name": "The OpenAssetOI logo",
+              "qualifiedName": "logos / openassetio / v1"
+            },
+            "openassetio-mediacreation:content.LocatableContent": {
+              "location": "file:///${bal_library_dir}/logo.jpg"
+            }
+          }
+        },
+        {
+          "traits": {
+            "openassetio-mediacreation:identity.DisplayName": {
+              "name": "The OpenAssetIO logo",
+              "qualifiedName": "logos / openassetio / v2"
+            },
+            "openassetio-mediacreation:content.LocatableContent": {
+              "location": "file:///${bal_library_dir}/logo_revised.jpg"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

examples/resources/versioning/openassetio_config.toml

@@ -0,0 +1,5 @@
+[manager]
+identifier = "org.openassetio.examples.manager.bal"
+
+[manager.settings]
+library_path = "${config_dir}/bal_database.json"