[Docs] Add Jupyter 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 <[email protected]>

Author: foundrytom

.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

README.md

@@ -1,6 +1,6 @@
 # OpenAssetIO-MediaCreation
 
-OpenAssetIO extensions for use in Media Creation
+A library of OpenAssetIO extensions for use in Media Creation workflows.
 
 > Note: This repository is currently in a pre-alpha state, and so should
 > not be used for any production critical applications.
@@ -13,6 +13,26 @@ MediaCreation is an automatically generated Python package,
 [openassetio-traitgen](https://github.com/OpenAssetIO/OpenAssetIO-TraitGen)
 is used to generate trait implementations based on [traits.yml](traits.yml)
 
+## Examples
+
+Code samples of how the Media Creation Traits and Specifications can be
+used in production workflows are available in the [examples](./examples)
+directory in form of [Jupyter](https://jupyter.org) notebooks.
+
+When [viewed in GitHub](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation/tree/main/examples)
+they will be fully rendered. They can also be explored locally:
+
+```bash
+git clone https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation.git
+cd OpenAssetIO-MediaCreation
+python -m venv .venv
+. ./.venv/bin/activate
+python -m pip install .
+python -m pip install -r examples/resources/requirements.txt
+cd examples
+jupyter notebook
+```
+
 ## Project status
 
 These initial incarnations of traits/specifications serve as