title: Parsing function docstring in sphinx.autodoc format
body: <p>I have many functions in Python of the type:</p>
  
  <pre><code>def foobar(one, two):
      """
      My function.
      :param int one: My one argument.
      :param int two: My two argument.
      :rtype: Something nice.
      """
      return 100 + one + two
  </code></pre>
  
  <p>And I need to parse the docstring to have a dictionary something like:</p>
  
  <pre><code>{
      'sdesc'  : 'My function.',
      'params' : [('one', 'My one argument.'), ('two', 'My two argument.')],
      'rtype'  : 'Something nice.'
  }
  </code></pre>
  
  <p>I can use <code>sphinx.util.docstrings.prepare_docstring</code> as follows:</p>
  
  <pre><code>&gt;&gt;&gt; prepare_docstring(foobar.__doc__)
  ['My function.', ':param int one: My one argument.', ':param int two: My two argument.', ':rtype: Something nice.', '']
  </code></pre>
  
  <p>I could create my own parser, maybe using regex for params and rtype, and stuff.</p>
  
  <p>But is there a better way to do it or a better approach? How <code>sphinx.ext.autodoc</code> does it? Any other advice on how to parse this kind of docstrings?</p>