document the three main plot functions provided by ba_plot (#1069)

hugo/content/ref/result/matplotlib.md

@@ -13,33 +13,73 @@ by function arguments, Matplotlib ressources, or environment variables.
 
 ### Plot invocation
 
-When running BornAgain through Python sripts, Matplotlib is invoked
-either directly, or indirectly through BornAgain functions like `run_and_plot`.
-For direct invocation, see the [Matplotlib documentation](https://matplotlib.org/stable/index.html).
-Here we are concerned with indirect invocation through standard BornAgain plot functions.
+In the BornAgain example scripts, Matplotlib is invoked through the following functions:
 
-The functions `run_and_plot`, `plot_simulation_result`, and a number of lower-level functions,
-are all implemented in the Python module
-[`plot_utils`]({{% url-src %}}/Wrap/python/plot_utils.py)
-that is part of the `bornagain` module.
-These functions support the keyword arguments
+##### plot_simulation_result
+
+`plot_simulation_result(result, **plotargs)` plots one 1D or 2D simulation result.
+
+The argument `result` is of type {{% ref-class "Device/Data" "Datafield" %}},
+as returned by the function `Simulation.simulate()`.
+
+The optional `plotargs` arguments are discussed below.
+
+##### plot_multicurve
+
+`plot_multicurve(results, **plotargs)` plots several 1D simulation results into one frame.
+
+The argument `results` is a list of {{% ref-class "Device/Data" "Datafield" %}}s.
+
+The optional `plotargs` arguments are discussed below.
+
+##### make_plot
+
+`make_plot(results, ncol, **plotargs)` plots several simulation results into as many different frames.
+
+The argument `results` is a list of {{% ref-class "Device/Data" "Datafield" %}}s.
+
+The argument `ncol` is the number of columns of the grid that holds the plot frames.
+
+The optional `plotargs` arguments are discussed below.
+
+### Optional plot arguments
+
+In the functions documented above, `**plotargs` stands for optional keyword arguments.
+These are supplied either directly like in
+```
+    result = simulation.simulate()
+    bp.plot_simulation_result(result, legendloc='lower right')
+    bp.plt.show()
+```
+or through a dictionary variable like in
+```
+    result = simulation.simulate()
+    plotargs = {}
+    plotargs['aspect'] = 'auto'
+    plotargs['intensity_min'] = 1e-12
+    plotargs['intensity_max'] = 1e2
+    bp.plot_simulation_result(result, **plotargs)
+    bp.plt.show()
+```
+
+Support keyword arguments include
 
 * `intensity_min`,
 * `intensity_max`,
 * `xlabel`,
 * `ylabel`,
 * `zlabel`,
-* `cmap`: heat map, see below,
+* `legendloc`: where a legend is placed.
 * `aspect`: [aspect ratio](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html), default is 'auto', other possible values are 'equal', or a number,
-* `noshow`: if `True`, run Matplotlib in batch mode, without displaying a plot.
+* `cmap`: heat map, see below.
+
+### Code location
 
-So if an example script contains the code line
-```python
-    ba.run_and_plot()
+The above documented functions are implemented in the Python module
+[`ba_plot`]({{% url-src %}}/Wrap/python/src/bornagain/ba_plot.py)
+that is typically imported with the line
 ```
-then the plot can be modified through keyword arguments like
-```python
-    ba.run_and_plot(cmap='jet', intensity_min=2e-8, intensity_max=2)
+from bornagain import ba_plot as bp
 ```
 
 ### Matplotlib resources

hugo/layouts/shortcodes/ref-class.html

-[{{ .Get 1}}]({{.Site.Params.url_blob}}/{{ .Get 0}}/{{ .Get 1}}.h)
+[{{ .Get 1}}]({{.Site.Params.url_blob}}/{{ .Get 0}}/{{ .Get 1}}.h){{- print "" -}}