code: def rst_to_docs_rst(infile, outfile):
      
  
      # Read infile into a list of lines
      with open(infile, 'r') as fin:
          rst = fin.readlines()
  
      # Inspect outfile path components to determine whether outfile
      # is in the root of the examples directory or in a subdirectory
      # thererof
      ps = pathsplit(outfile)[-3:]
      if ps[-2] == 'examples':
          ps = ps[-2:]
          idx = 'index'
      else:
          idx = ''
  
      # Output string starts with a cross-reference anchor constructed from
      # the file name and path
      out = '.. _' + '_'.join(ps) + ':\n\n'
  
      # Iterate over lines from infile
      it = iter(rst)
      for line in it:
          if line[0:12] == '.. toc-start':  # Line has start of toc marker
              # Initialise current toc array and iterate over lines until
              # end of toc marker encountered
              toc = []
              for line in it:
                  if line == '\n':  # Drop newline lines
                      continue
                  elif line[0:10] == '.. toc-end':  # End of toc marker
                      # Add toctree section to output string
                      out += '.. toctree::\n   :maxdepth: 1\n\n'
                      for c in toc:
                          out += '   %s <%s>\n' % c
                      break
                  else:  #  Still within toc section
                      # Extract link text and target url and append to
                      # toc array
                      m = re.search(r'`(.*?)\s*<(.*?)(?:.py)?>`', line)
                      if m:
                          if idx == '':
                              toc.append((m.group(1), m.group(2)))
                          else:
                              toc.append((m.group(1),
                                          os.path.join(m.group(2), idx)))
          else:  # Not within toc section
              out += line
  
      with open(outfile, 'w') as fout:
          fout.write(out)
docs: Convert an rst file to a sphinx docs rst file.