[ev-br]

closes gh-14

Make the examples' README files executable. The end goal is to satisfy:

• to keep README examples current, they execute on CI.
• examples are in human-readable markdown, and can be read from the terminal.
• the full output can be seen from the CI logs;
• examples can be transformed to html and placed on the web documentation.

For running on CI, there will be two runs:

• In this repository, the CI runs on each PR,against the benchx from pypi;
• In the benchx repository, the same README executes on CI for each benchx PR using the main branch of benchx_examples

This PR starts the process from the pyperf-suite example (which actually already drifted): it adds a CI workflow to execute examples/pyperf-suire/README.md. Two sets of moving parts:

• a reusable workflow. This sets scaffolding to run the same workflow here and in benchx CI with minimal duplication;
• the executable markdown format. A classic tool is jupytext with MYST-markdown, but for now I'm using a simpler tech: markdown-it-py to parse executable blocks from a markdown file + an ad-hoc script to parse it with the following rules for markdown fences:

```bash
this is a bash command
``` 

executes a shell command.

```python
here is python code
```

executes python code

```text
this is output
```

is an example output. The first text fence which follows a sh, bash or python fence is replaced by the actual output; other fences or unfenced triple backticks are preserved as is:

```
this looks like code, but it is never run
```

---

While I'm not loving a 300-odd LOC python script for parsing markdown, it seems simple enough to not use a blunt general-purpose tool that MYST-markdown is. If it runs out of steam going forward, reusing MYST is easy enough.
FWIW, what I like of the current DIY solution is that it's easy to keep things readable in terminal (Myst-markdown is geared towards full-fledged jupyter notebooks and strips all output)