Cleanup Python scripts: no more show_or_export, no more parsing command-line arguments

Background: Upon importing ba_plot, command-line arguments are parsed. This was used more intensely in the past; arguments with sim_ prefix have been declared obsolete in v21. Command-line arguments can still be used to modify plots, or to export fit results to a data file. The latter possibility is hinted at by the function called show_or_export in all scripting examples. However, there seems to be no documentation of supported command-line arguments. Anyway, the main remaining usage of command-line arguments is in testing: All our Py tests are run with show=n, and all persistence tests with figfile=....

Problem: What happens when ba_plot is imported in a different environment is completely random. For instance in a Jupyter Notebook, the commandline includes some extra arguments, say --notebook --no-exit -p 1; these are added (& understood) internally by JupyterLab but do not follow the rules expected in ba_plot. Yet, the automatic parse_commandline() call in ba_plot receives all these extra arguments and hence, it fails since it cannot understand them.

Solution: The function parse_commandline() must disappear from ba_plot. Actually, this is an opportunity to remove all test-related instrumentation from the sight of users. Instead, for testing scripts we shall use the new mechanism of processing raw example scripts with the erb text processor.

  • In the published version of all scripts, replace show_or_export() by show().
  • In the raw version of scripts, use an erb macro to support the export of figure or data files for use in persistence test and documentation autogeneration.
  • Remove parse_commandline() and related code from ba_plot.
  • Provide documentation how to modify matplotlib settings from a ba script.
  • Provide documentation how to modify a script so that it directly yields an image file without launching the interactive matplotlib widget. - done in !2928 (merged)
  • Provide documentation how to modify a script so that it yields a data file. - won't do; this is for internal use only

Acknowledgements: Thanks to Hiroyuki Aoki (J-PARC) for reporting the Jupyter issue, and to @a.nejati for analysing and insisting that ba_plot needs to be changed.

Edited by Joachim Wuttke