Embed execution environment metadata in MyST documents

[choldgraf]

Description

Many MyST documents represent analyses and computations that require a particular environment in order to run. When MyST is used as an entrypoint into computational environments, it requires knowing what software needs to be present in the analysis in order to successfully execute.

MyST already has a mechanism for defining metadata for each page in a project. If pages have different software environment requirements, allowing a user to define these environments could allow projects like Binder, JupyterHub, or Thebe to build and load the proper environment on the fly.

This could be a way to increase the reproducibility and provenance of documents built with MyST, and to make it easier to share MyST content as self-contained text files.

An example from Python

Recently there have been some efforts at embedding metadata within Python scripts. The inline script metadata specification is now a formal way to embed metadata in scripts. This is supported by Hatch to auto-build environments.

A simple example in MyST

A simple example of what this might look like:

---
env:
  type: (specifies the installation command, dependent on the language of the kernel as defined in a `jupyter` block)
  items:
    - item1
    - item2
    - Each is installed by the method implied by `type:`
---
# My MyST title
...