[python] Provide better examples of graphics in a Python script

Show two relevant use cases:

- The user wants to plot static objects to a canvas and the canvas should survive and be displayed to screen.
- The user wants to fill a graphical object and display updates live on a canvas, then make it survive before the function ends.

Author: vepadulano

bindings/pyroot/pythonizations/python/ROOT/_pythonization/_tcanvas.py

@@ -8,69 +8,106 @@
 # For the list of contributors see $ROOTSYS/README/CREDITS.                    #
 ################################################################################
 
-r'''
+r"""
 \pythondoc TCanvas
 
-Functionality of TCanvas::Update() method was extended to support interactive
-graphics in the python scripts. If extra block parameter is True, script execution
-will be suspended until <space> key pressed by user. Simple example:
+The TCanvas class is used to create the canvas on which graphical objects such as histograms can be drawn. The following
+is a simple example of typical usage:
 
 \code{.py}
 import ROOT
+import numpy
 
-c = ROOT.TCanvas()
-h = ROOT.TH1I("h1", "h1", 100, -5, 5)
-h.FillRandom("gaus", 10000)
-h.Draw("")
 
-# block here until space is pressed
-c.Update(True)
+def plot():
+    h = ROOT.TH1D("h", "h", 100, -5, 5)
+    h.Fill(numpy.random.normal(size=1000))
 
-# continues after <space> is pressed
-c.SaveAs("canvas.root")
+    c = ROOT.TCanvas()
+    h.Draw()
+    c.Draw(block=True)
+
+
+if __name__ == "__main__":
+    print("Before plot function")
+    plot()
+    print("After plot function")
+\endcode
+
+Note the optional argument `block` passed to the `Draw` method of the canvas. If set to `True`, it will block the script
+execution and run the ROOT graphics event loop until the <space> key is pressed. This allows interacting with the
+canvas and its content until necessary, then move on with the rest of the script.
+
+Another relevant use case is drawing live updates on a canvas, shown in the example below. In this case, the canvas is
+setup by first creating the object to be drawn and drawing it once. Then, the object is updated in a for loop, which
+could represent for example an incoming stream of data with which the histogram should be filled. Each time the plot
+should be updated, the `ModifiedUpdate` function should be called. This will immediately show the new contents on the
+plot. Finally, the canvas is drawn again with `Draw(block=True)` at the end of the loop so that it stays visible and can
+be interacted with.
+
+\code{.py}
+import ROOT
+import numpy
+
+
+def live_update():
+    c = ROOT.TCanvas()
+    h = ROOT.TH1D("h", "h", 100, -5, 5)
+
+    h.Draw()
+    for _ in range(100):
+        h.Fill(numpy.random.normal(size=10))
+        c.ModifiedUpdate()
+    c.Draw(block=True)
+
+if __name__ == "__main__":
+    print("Before plot function")
+    live_update()
+    print("After plot function")
 \endcode
+
 \endpythondoc
-'''
+"""
 
 from . import _run_root_event_loop, pythonization
 
 
-def _TCanvas_Update(self, block = False):
-   """
-   Updates the canvas.
-   Also blocks script execution and runs the ROOT graphics event loop until the <space> keyword is pressed,
-   but only if the following conditions are met:
-   * The `block` optional argument is set to `True`.
-   * ROOT graphics are enabled, i.e. `ROOT.gROOT.IsBatch() == False`.
-   * The script is running not in ipython notebooks.
-   """
+def _TCanvas_Update(self, block=False):
+    """
+    Updates the canvas.
+    Also blocks script execution and runs the ROOT graphics event loop until the <space> key is pressed,
+    but only if the following conditions are met:
+    * The `block` optional argument is set to `True`.
+    * ROOT graphics are enabled, i.e. `ROOT.gROOT.IsBatch() == False`.
+    * The script is not running in ipython notebooks.
+    """
 
-   self._Update()
+    self._Update()
 
-   # run loop if block flag is set
-   if block:
-      _run_root_event_loop()
+    # run loop if block flag is set
+    if block:
+        _run_root_event_loop()
 
 
 def _TCanvas_Draw(self, option: str = "", block: bool = False):
-   """
-   Draw the canvas.
-   Also blocks script execution and runs the ROOT graphics event loop until the <space> keyword is pressed,
-   but only if the following conditions are met:
-   * The `block` optional argument is set to `True`.
-   * ROOT graphics are enabled, i.e. `ROOT.gROOT.IsBatch() == False`.
-   * The script is running not in ipython notebooks.
-   """
+    """
+    Draw the canvas.
+    Also blocks script execution and runs the ROOT graphics event loop until the <space> is pressed,
+    but only if the following conditions are met:
+    * The `block` optional argument is set to `True`.
+    * ROOT graphics are enabled, i.e. `ROOT.gROOT.IsBatch() == False`.
+    * The script is not running in ipython notebooks.
+    """
 
-   self._Draw(option)
+    self._Draw(option)
 
-   # run loop if block flag is set
-   if block:
-      self._Update()
-      _run_root_event_loop()
+    # run loop if block flag is set
+    if block:
+        self._Update()
+        _run_root_event_loop()
 
 
-@pythonization('TCanvas')
+@pythonization("TCanvas")
 def pythonize_tcanvas(klass):
     # Parameters:
     # klass: class to be pythonized
@@ -79,4 +116,3 @@ def pythonize_tcanvas(klass):
     klass._Draw = klass.Draw
     klass.Update = _TCanvas_Update
     klass.Draw = _TCanvas_Draw
-