Parsing function docstring in sphinx.autodoc format

Question

I have many functions in Python of the type:

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

And I need to parse the docstring to have a dictionary something like:

{
    'sdesc'  : 'My function.',
    'params' : [('one', 'My one argument.'), ('two', 'My two argument.')],
    'rtype'  : 'Something nice.'
}

I can use sphinx.util.docstrings.prepare_docstring as follows:

>>> prepare_docstring(foobar.__doc__)
['My function.', ':param int one: My one argument.', ':param int two: My two argument.', ':rtype: Something nice.', '']

I could create my own parser, maybe using regex for params and rtype, and stuff.

But is there a better way to do it or a better approach? How sphinx.ext.autodoc does it? Any other advice on how to parse this kind of docstrings?

Answer 1

openstack/rally's parse_docstrings() (permalink) take a function's docstring in reStructuredText (reST) format as an input and returns 4 values-short_description, long_description, params and returns

For e.g. if the function and its docstring is

def sample(self, task, deployment=None):
    """Start benchmark task.

    Implement sample function's long description.

    :param task: Path to the input task file.
    :param deployment: UUID or name of the deployment

    :returns: NIL
    """

Then parse_docstrings() function will return-

{ "short_description" : "Start benchmark task.",
  "long_description" : "Implement sample function's long description.",
  "params": [ { "name" : "task", "doc": "Path to the unput task file" },
              { "name" : "deployment", "doc" :  "UUID or name of the deployment" } ]
  "returns" : "NIL"
}

You can modify the above function as per your needs.

Answer 2

EDIT:

This question had two years without a response. See the accepted response for a better option.

---

OLD:

I ended up using regular expressions. The particular system used by Sphinx of nested Nodes, where each node type has to parse their children is not very useful for my purposes. If someone care, this is the regex I used:

param_regex = re.compile(
    '^:param (?P<type>\w+)? (?P<param>\w+): (?P<doc>.*)$'
)

Answer 3

pip install docstring-parser

support both ReST-style and Google-style docstrings,

see https://github.com/rr-/docstring_parser for details