Library scope

[OriolAbril]

Thanks for working on this, I would love to use such a tool. I am not familiar with the libraries this is built on top of and I am not particularly free, but I would be happy to try things out and help with documentation.

So far I did a very quick test and noticed two things: #5 and the fact that complex types (e.g. a dictionary where we document the types of the keys and values) prefer a type-hint-like syntax, and only the most basic cases support a more readable alternative. numpydoc itself is quite vague on that, its examples have int or tuple of int as the most complicated type, but both pandas and matplotlib extend that and define things like dict of {str : array_like} to specify the types of keys and values, or (float, float) to indicate a tuple of two floats like figsize.

I saw that including the shape info in the type is supported, which is another "community extension" of numpydoc. Are these syntaxes in scope? If so, what would help work on that?

[lagru]

Hey @OriolAbril, thanks for your interest! :D

Re "more complex readable types", I'm totally open to supporting more of those, especially if the community is already using them. The reason your some of your examples aren't working right now is only because I was focused on the array types and scikit-image's needs initially.

Two ways I plan to support those is either directly in docstub or via extended configuration by the library on which docstub is run. So the challenge will probably be to identify a sensible set of for the core grammar. I also hope that docstub will have somewhat of a consolidating effect on the ecosystem. What do you think? I'd love to collaborate with you on this. Note that you can also play around with the grammar by using Lark's online IDE and pasting the current grammar.

I also I don't want the grammar to become ambiguous. So e.g. a two-element tuple (x, y) must be differentiable from a shape (x, y) in context of an array.

[OriolAbril]

I have opened #7 to try and get the examples in the pandas docstring guide working, doesn't really work yet though.

[lagru]

Note that the dict of {x: int} syntax is supported now:

docstub/src/docstub/doctype.lark

Line 44 in 72ff2a0

| qualname "of" "{" type ":" type "}"

docstub/tests/test_docstrings.py

Line 52 in 72ff2a0

("dict of {str: int}", "dict[str, int]"),

I'm willing to try out the (x, y, ...) syntax as an alternative to tuple[x, y, ...]. But I'm also worried that allowing to many options will bite us down the line?

[OriolAbril]

I have seen, thanks! At least in the libraries I work with it is definitely much more common than the tuple one.

I am also perfectly happy with the "pandas way" tuple of (str, int, int) (I think already works) or tuple of (str,) (definitely works already). AFAIK the "tuple-ness" of parenthesis outside of shapes is matplotlib specific. I am not sure if it is something that needs to be handled now or if it could be added at a similar cost later. If it can be added later maybe wait and see if anyone else complains about it missing?