docs: def generate_file_rst(fname, target_dir, src_dir, plot_gallery):
      """ Generate the rst file for a given example.
      """
      base_image_name = os.path.splitext(fname)[0]
      image_fname = '%s_%%s.png' % base_image_name
      root_image_fname = 'root_%s_%%s.png' % base_image_name
      root_fig_num = 1
  
      this_template = rst_template
      last_dir = os.path.split(src_dir)[-1]
      # to avoid leading . in file names, and wrong names in links
      if last_dir == '.' or last_dir == 'examples':
          last_dir = ''
      else:
          last_dir += '_'
      short_fname = last_dir + fname
      src_file = os.path.join(src_dir, fname)
      example_file = os.path.join(target_dir, fname)
      shutil.copyfile(src_file, example_file)
  
      # The following is a list containing all the figure names
      figure_list = []
  
      image_dir = os.path.join(target_dir, 'images')
      thumb_dir = os.path.join(image_dir, 'thumb')
      if not os.path.exists(image_dir):
          os.makedirs(image_dir)
      if not os.path.exists(thumb_dir):
          os.makedirs(thumb_dir)
      image_path = os.path.join(image_dir, image_fname)
      root_image_path = os.path.join(image_dir, root_image_fname)
  
      stdout_path = os.path.join(image_dir,
                                 'stdout_%s.txt' % base_image_name)
      time_path = os.path.join(image_dir,
                                 'time_%s.txt' % base_image_name)
      thumb_file = os.path.join(thumb_dir, fname[:-3] + '.png')
      time_elapsed = 0
      if plot_gallery and fname.startswith('plot'):
          # generate the plot as png image if file name
          # starts with plot and if it is more recent than an
          # existing image.
          first_image_file = image_path % 1
          first_root_image_file = root_image_path % 1
          if os.path.exists(stdout_path):
              stdout = open(stdout_path).read()
          else:
              stdout = ''
          if os.path.exists(time_path):
              time_elapsed = float(open(time_path).read())
  
          if (not os.path.exists(first_image_file) or
              not os.path.exists(first_root_image_file) or
                  os.stat(first_image_file).st_mtime <=
                                      os.stat(src_file).st_mtime):
              # We need to execute the code
              print('plotting %s' % fname)
              t0 = time()
              import matplotlib.pyplot as plt
              plt.close('all')
              cwd = os.getcwd()
              try:
                  # First CD in the original example dir, so that any file
                  # created by the example get created in this directory
                  orig_stdout = sys.stdout
                  os.chdir(os.path.dirname(src_file))
                  my_buffer = StringIO()
                  my_stdout = Tee(sys.stdout, my_buffer)
                  sys.stdout = my_stdout
                  my_globals = {'pl': plt}
                  execfile(os.path.basename(src_file), my_globals)
                  time_elapsed = time() - t0
                  sys.stdout = orig_stdout
                  my_stdout = my_buffer.getvalue()
                  if '__doc__' in my_globals:
                      # The __doc__ is often printed in the example, we
                      # don't with to echo it
                      my_stdout = my_stdout.replace(
                                              my_globals['__doc__'],
                                              '')
                  my_stdout = my_stdout.strip()
                  if my_stdout:
                      stdout = '**Script output**::\n\n  %s\n\n' % (
                          '\n  '.join(my_stdout.split('\n')))
                  open(stdout_path, 'w').write(stdout)
                  open(time_path, 'w').write('%f' % time_elapsed)
                  os.chdir(cwd)
  
                  # In order to save every figure we have two solutions :
                  # * iterate from 1 to infinity and call plt.fignum_exists(n)
                  #   (this requires the figures to be numbered
                  #    incrementally: 1, 2, 3 and not 1, 2, 5)
                  # * iterate over [fig_mngr.num for fig_mngr in
                  #   matplotlib._pylab_helpers.Gcf.get_all_fig_managers()]
                  for fig_num in (fig_mngr.num for fig_mngr in
                          matplotlib._pylab_helpers.Gcf.get_all_fig_managers()):
                      # Set the fig_num figure as the current figure as we can't
                      # save a figure that's not the current figure.
                      plt.figure(fig_num)
                      plt.savefig(image_path % fig_num)
                      figure_list.append(image_fname % fig_num)
                  for canvas in ROOT.gROOT.GetListOfCanvases():
                      maybe_root_filename = os.path.join(os.path.dirname(src_file), canvas.name)
                      if os.path.isfile(maybe_root_filename):
                          os.rename(maybe_root_filename, os.path.join(image_dir, canvas.name))
                          figure_list.append(canvas.name)
                          canvas.Close()
                      else:
                          canvas.SaveAs(root_image_path % root_fig_num)
                          canvas.Close()
                          figure_list.append(root_image_fname % root_fig_num)
                          root_fig_num += 1
              except:
                  print(80 * '_')
                  print('%s is not compiling:' % fname)
                  traceback.print_exc()
                  print(80 * '_')
              finally:
                  os.chdir(cwd)
                  sys.stdout = orig_stdout
  
              print(" - time elapsed : %.2g sec" % time_elapsed)
          else:
              figure_list = [f[len(image_dir):]
                              for f in glob.glob(image_path % '[1-9]')]
                              #for f in glob.glob(image_path % '*')]
  
          # generate thumb file
          this_template = plot_rst_template
          from matplotlib import image
          if os.path.exists(first_image_file):
              image.thumbnail(first_image_file, thumb_file, 0.2)
          elif os.path.exists(first_root_image_file):
              image.thumbnail(first_root_image_file, thumb_file, 0.2)
  
      if not os.path.exists(thumb_file):
          # create something not to replace the thumbnail
          shutil.copy('images/blank_image.png', thumb_file)
  
      docstring, short_desc, end_row = extract_docstring(example_file)
  
      # Depending on whether we have one or more figures, we're using a
      # horizontal list or a single rst call to 'image'.
      if len(figure_list) == 1:
          figure_name = figure_list[0]
          image_list = SINGLE_IMAGE % figure_name.lstrip('/')
      else:
          image_list = HLIST_HEADER
          for figure_name in figure_list:
              image_list += HLIST_IMAGE_TEMPLATE % figure_name.lstrip('/')
  
      f = open(os.path.join(target_dir, fname[:-2] + 'rst'), 'w')
      f.write(this_template % locals())
      f.flush()