Merging branch 'm.i970f'  into 'main'.

See merge request !2719

Merging branch 'm.export_to_py'  into 'main'.

See merge request !2720

Merging branch 'm.i970e'  into 'main'.

See merge request !2717

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

Related to issue #864

Adapted also 'publicmode.erb' and 'testmode.erb' files.

* variable:
'sm' -> 'test_mode'

* files:
longmode.rb -> publicmode.rb
shortmode.rb -> testmode.rb

Merging branch 'a.restoreRefData'  into 'main'.

The reference data for 'MiniExample' tests are restored from commit 092b75b3.


See merge request !2716

The test reference data are restored from commit 092b75b3.

The test reference data are restored from commit 092b75b3.

The test reference data are restored from commit 092b75b3.