code: def rst2md(text):
      
  
      top_heading = re.compile(r'^=+$\s^([\w\s-]+)^=+$', flags=re.M)
      text = re.sub(top_heading, r'# \1', text)
  
      math_eq = re.compile(r'^\.\. math::((?:.+)?(?:\n+^  .+)*)', flags=re.M)
      text = re.sub(math_eq,
                    lambda match: r'\begin{{align}}{0}\end{{align}}'.format(
                        match.group(1).strip()),
                    text)
      inline_math = re.compile(r':math:`(.+?)`', re.DOTALL)
      text = re.sub(inline_math, r'$\1$', text)
  
      directives = ('warning', 'note')
      for directive in directives:
          directive_re = re.compile(r'^\.\. %s::((?:.+)?(?:\n+^  .+)*)'
                                    % directive, flags=re.M)
          text = re.sub(directive_re,
                        partial(directive_fun, directive=directive), text)
  
      links = re.compile(r'^ *\.\. _.*:.*$\n', flags=re.M)
      text = re.sub(links, '', text)
  
      refs = re.compile(r':ref:`')
      text = re.sub(refs, '`', text)
  
      contents = re.compile(r'^\s*\.\. contents::.*$(\n +:\S+: *$)*\n',
                            flags=re.M)
      text = re.sub(contents, '', text)
  
      images = re.compile(
          r'^\.\. image::(.*$)(?:\n *:alt:(.*$)\n)?(?: +:\S+:.*$\n)*',
          flags=re.M)
      text = re.sub(
          images, lambda match: '![{1}]({0})\n'.format(
              match.group(1).strip(), (match.group(2) or '').strip()), text)
  
      return text
docs: Converts the RST text from the examples docstrigs and comments
      into markdown text for the Jupyter notebooks