OpenAssetIO / OpenAssetIO-MediaCreation

OpenAssetIO extensions for use in the Media Creation industry.
Apache License 2.0
12 stars 10 forks source link

Add Jupyter notebook for versioning workflows #59

Closed foundrytom closed 11 months ago

foundrytom commented 1 year ago

Based on @feltech's excellent start on a notebook for versioning, this hopefully covers all of the methods we removed from the core API and added to MC as custom traits/specifications in #51.

Needs a good proof read, and feedback on content structure.

I've omitted cell output in this version, but we discussed including it so GitHub would render it in its viewer.

feltech commented 1 year ago

Structure looks great to me, not too narrative at all, and broken up just about right - if anything, the getWithRelationship code boxes could be more broken up, to explain line by line. E.g. explaining the imports first, and replacing code comments with markdown sections.

I'll put aside spelling/grammar issues for now :grin: As well as content suggestions.

Not sure about including the pip install in the notebook, since it pollutes the users Python environment without asking. I think better to provide a requirements.txt. I suspect most readers would prefer to jump to a pre-rendered non-interactive doc in the first instance (or perhaps a web-hosted notebook), rather than configuring a local jupyter environment. We can discuss how best to provide that as a separate issue.

elliotcmorris commented 1 year ago

I'm not sure about the pip installs, if the user is running the notebook locally, they are fairly convenient.

In any case, if they remain we'll probably want to do

import sys
!{sys.executable} -m pip install openassetio

instead of !pip install, for similar reasons we do python -m pip install, there's a jupyter specific explanation here : https://jakevdp.github.io/blog/2017/12/05/installing-python-packages-from-jupyter/#How-to-use-Pip-from-the-Jupyter-Notebook

foundrytom commented 11 months ago

@feltech @elliotcmorris Just added this to the instructions, to make sure that if you use the checkout, you get MC from src.