CODEWITHSUNDEEP
pythonpython-sphinxdocstring
Havok
Havok

Reputation: 5882

Parsing function docstring in sphinx.autodoc format

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?

Upvotes: 14

Views: 6803

Answers (3)

Felix Liu
Felix Liu

Reputation: 327

pip install docstring-parser

support both ReST-style and Google-style docstrings,

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

Upvotes: 3

piyush_raman
piyush_raman

Reputation: 318

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.

Upvotes: 14

Havok
Havok

Reputation: 5882

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>.*)$'
)

Upvotes: 2

Related Questions