Merging branch 'a.newExamples'  into 'main'.

A multi-line Ruby macro is used to differentiate between the Examples presented to the user from those which are used for testing.
For instance,
```
<%- if test_mode -%>
plotargs = bp.parse_commandline()
bp.make_plot_row(results, **plotargs)
bp.export(**plotargs)
<%- else -%>
bp.make_plot_row(results)
plt.show()
<%- end -%>
```
which for the test mode reduces to 
```
plotargs = bp.parse_commandline()
bp.make_plot_row(results, **plotargs)
bp.export(**plotargs)
```
and, for the public user script, to
```
bp.make_plot_row(results)
plt.show()
```

Hence, in this way, the details of the test scripts remains hidden from the user, and the script remains readable and less error-prone, regarding long-term maintenance.

* Another mode, `figure_mode`, is added to produce the figures for the documentation (via `figures` target).

* The unneeded function `show_or_export` is removed from `ba_plot`. Instead, a new function `export(**plotargs)` is added to `ba_plot` and whenever showing the plot is needed, the standard `matplotlib.pyplot.show` must be used.

* `auto/MiniExamples` and `auto/Examples` are reproduced.

* The following reference data are updated:
  - specular/SpecularSimulationWithRoughness
  - specular/RoughnessModel
  - specular/MagneticLayerImperfect
  - scatter2d/CorrelatedRoughness
  - scatter2d/CoreShellNanoparticles2
  - offspec/OffspecResolved


* Problem: `Example.scatter2d.RoughAndSpecular.persist` does not pass on MacOS-ARM CI machine, although it is passed on Linux, Windows and MacOS-x64 CI machines. Reasons are to be investigated; see issue #864 .


Related to issues #912 and #1008

See merge request !2663