# Personas and stories for computation in MyST

## Background
MyST presently has two completely independent execution mechanisms:

Static execution
: Execution of code at build-time via `myst build --execute`.

Interactive execution
: Execution of code at read-time via Thebe (aka [in-browser execution](https://mystmd.org/guide/integrating-jupyter)).

These occur at different times, and serve different kinds of audiences. The purpose of this document is to learn more about the kinds of "personas" and their user stories around execution in MyST.

> [!Warning]
> This needs refinement to specify text-based vs .ipynb notebooks.
> Best-practice nearly always prefers text-based notebooks.

## Personas and stories

### An arbitrary persona wants to publish an online textbook

* These notebooks may be executable.
* They want to have reliable reproducible builds in CI.
* They may want to pre-execute in a particular compute environment.

### An instructor publishes their courseware

* Their courseware is predominantly in notebooks with some markdown content.
* They have worksheets that are executable, and students are expected to fill in the blanks with their solutions.
* Instructors have reference solutions and want to be able to validate them e.g. in CI
* Reference solutions should/may be visible to students to copy-paste and/or otherwise pull in.
* Instructors may prefer students to remain inside the MyST site to do this.

### A community maintainer creates a dashboard with MyST

- Usage statistics of their GitHub Repo are compiled by a notebook.
- The code-cells are run at build time to analyse data and generate content:
- Tables; Pandas, Markdown
- Arbitrary content
- Figures: interactive plots and widgets
- The resulting document is pushed to the web as an HTML build.

### An Executive Director creates a monthly report

- Financial data for the last month is scraped using an executable MyST document.
- Some Markdown content outside of the code cells includes `{eval}` roles which utilise the data computed in other code-cells.
- The code-cells are run at build time to analyse data and generate content:
- Figures (plots)
- Tables; Pandas, Markdown
- Equations (TeX-math, Typst?)
- Arbitrary content
- The resulting document is published to a PDF via Typst.

### A scientist publishes a reproducible paper

- They have some (maybe hidden) notebooks generating interesting outputs like figures and tables.
- The notebooks are run at build time to ensure a reproducible build
- They either write their main manuscript in Markdown or TeX embedding:
- Notebook outputs as figures to tables.
- Code cells and programs.
- OR, they write the paper in a top-to-bottom notebook(s).

### A scientist publishes a computational article

- The authors have included a mix of static and interactive figures, all of which are generated by notebooks.
- The notebooks are run at build time to ensure a reproducible build.
- The code-cells analyse data and generate interesting figures (plots, tables) _that will be interactive_.
- They include interactive figures for data exploration, visualisation etc.
- Some outputs are useable as static representations of the interactive cells (static plots)
- Other outputs require manual placeholders (widgets)
- They either write their main manuscript in Markdown:
- Notebook outputs as figures to tables.
- Code cells and programs.
- OR, they write the paper in a top-to-bottom notebook(s)