Support docstring formats: Google, NumPy, ReST

[SamuelMarks]

GitHub just suggested your repo to me, maybe you want to use my library?
https://github.com/offscale/cdd-python

You could implement diffs betwixt the IR (a dictionary) and then reverse it down to the Python code that produced that IR and highlighting where they differ. Wouldn't be so difficult.

Anyway just my 2¢

[pawamoy]

Hello! Thanks but I don't follow. What's an IR?What do you mean by diff? Why would I need Python code reversed from... what? 😅 And what does all this have to do with docstrings?

[astrojuanlu]

I didn't quite get what IR @SamuelMarks refers to, but regardless, it would be great if griffe could parse Google and NumPy docstrings as well. I see that https://mkdocstrings.github.io/griffe/griffe.json has a parsed section for docstrings, but I did a local test that used NumPy-style docstrings and it doesn't.

Since cdd-python knows how to convert between docstring formats, maybe it could be used.

[astrojuanlu]

See also gh-5.

[astrojuanlu]

On second inspection, I see on https://github.com/mkdocstrings/griffe/blob/7bf49528541e211af37c2ac5c1a74a4523699c65/src/griffe/docstrings/parsers.py that there are already several parsers, so those styles are already supported?

[SamuelMarks]

@pawamoy @astrojuanlu What my library allows you to do is to parse/emit docstrings (and other things, like functions and classes). Including when the docstring only tells half the story, e.g., there are explicit type annotations.

IR refers to intermediate representation.

Parse {function,class,docstring,argparse,sqlalchemy,pydantic,json_schema}
   /\
  /  \
 /    \
--    --
 | IR |
--    --
 \    /
  \  /
   \/
Emit {function,class,docstring,argparse,sqlalchemy,pydantic,json_schema}

Specifically on the docstring side you can parse/emit; with/without explicit type annotations; in ReST; NumPy; and Google formats.

As for how to use the library, see the docstring docstring: https://github.com/offscale/cdd-python/blob/d6226df/cdd/docstring/parse.py#L8-L39 ; TL;DR

import cdd.docstring.parse
import cdd.docstring.emit


ir = cdd.docstring.parse.docstring("my docstring goes here")
print(cdd.docstring.emit.docstring(ir, docstring_format="numpydoc"))

[pawamoy]

Thanks @SamuelMarks for the explanation, it's a bit more clear now (I still don't understand how Griffe could use your project though, unless I dive a bit more in the code/docs or you give examples).

@astrojuanlu Griffe is able to parse Google, Numpy and Sphinx docstrings, you can specify the style to parse with the -d CLI option or with the docstring parser arguments programmatically (look at the Griffe loader signature and parameters).

[pawamoy]

I'll close this as there does not seem to be anything actionable for Griffe here. Feel free to comment further 🙂