Provide a way to store execution output on selected code blocks

[mforbes]

Proposal

Provide some way of executing cells and storing the output for display on other servers without re-executing the cell.

Additional notes

One use case is documenting the performance characteristics of a particular platform/machine. I would like to be able to execute a cell on that machine, then store the results for posterity in the documentation. Not sure exactly how to do this, but one manual mechanism would be to provide a markdown representation of the output that one could right-click and copy (similar to how MathJaX cells allow you to copy different representations). Once could then paste this into the documentation and remove {code-cell} from the cell to make it static.

One could imagine more sophisticated mechanisms:

• only executing the cell on certain platforms or on machines with some sort of custom id
• storing the output in some sort of output file and using that if it exists - thus, committing that file to your repo would prevent execution on other platforms. There should be some sort of flag in the code (maybe the filename) so that users are alerted to this. E.g.:

  ```{code-cell}
  :output_filename: HPC_benchmarks.out
  %%timeit 1+1
  ```
  

  If HPC_benchmarks.out exists, then it will be loaded (maybe with a message on the console) rather than executing the cell.

[choldgraf]

As one workaround, could you use an IF statement in the cell's logic, whereby it:

1. looks for a file on disk (e.g. output_cell1.md)
2. if it does not find it, runs code that generates output_cell1.md.
3. if it does find it, loads and displays output_cell1.md

[mforbes]

Is there an easy way to generate output_cell1.md? That would make this a good workaround. How do I capture the output in markdown format?

[agoose77]

The MyST engine uses an execution cache in _build/execute, where the execution outputs for each file are stored. If you back that up, it will be used instead of re-execution. We don't officially support that use case, but we definitely want to expose the caching behaviour of execution eventually.

Would per-file execution solve your use case?

[mforbes]

In general, per-file execution is not what I am looking for, but if that is easy to do, then that would be a start. The main problem would be bloat: usually I have a descriptive document with many examples that should be run on build, but then might want one or two that are very slow and which should be built once. If I cache the entire file, the repo will get large.

I will try to play a bit with _build/execute to see if I can work something. (Note: it looks like _build/jupyter_execute on my machine - is this the same thing?)