解析 sphinx.autodoc 格式的函数文档字符串

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 eg 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