Clean up the Examples provided to the user (Major change)

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 .

Some examples of the applied modifications to raw examples:

<%= sm ? "plt.close() # " : "" %>plt.show()

becomes

<%- if test_mode -%>
plt.close()
<%- else -%>
plt.show()

plotargs = bp.parse_commandline()
bp.make_plot_row(results, **plotargs)
bp.show_or_export(**plotargs)

becomes

<%- if test_mode or figure_mode -%>
plotargs = bp.parse_commandline()
bp.make_plot_row(results, **plotargs)
bp.export(**plotargs)
<%- else -%>
bp.make_plot_row(results)
plt.show()
<%- end -%>

<%= sm ? "plt.close() # (hide plot) " :"" %>fit_objective.initPlot(10, plotter)

becomes

<%- if test_mode -%>
plt.close() # hide plot
<%- else -%>
fit_objective.initPlot(10, plotter)

bp.parse_args(intensity_min=1, aspect='auto')
sample = get_sample()
simulation = get_simulation(sample)
result = simulation.simulate()
bp.plot_simulation_result(result)
bp.show_or_export()

becomes

sample = get_sample()
simulation = get_simulation(sample)
result = simulation.simulate()
<%- if test_mode -%>
plotargs = bp.parse_commandline()
plotargs['intensity_min'] = 1
plotargs['aspect'] = 'auto'
bp.plot_simulation_result(result, **plotargs)
bp.export(**plotargs)
<%- else -%>
bp.plot_simulation_result(result)
plt.show()
<%- end -%>

Related to issues #912 (closed) and #1008 (closed)