Documentation: signatures with typehints.

[pfebrer]

Function signatures with typehints in the documentation can become very hard to read:

I been playing with some CSS, and it is possible to have each parameter in a new line, just as you would do in the source code:

Do you think it would be better?

[pfebrer]

You can tune it further to make it even clearer by adding colors for example:

[pfebrer]

Or even with the weight of the font, here I avoid setting the typehint to bold:

So, really you can do anything you come up with.

The way I did it applies the styling to methods as well, but I'm sure there's some way to avoid it:

[pfebrer]

Perhaps we can do a poll on discord to see which layout users prefer :)

[zerothi]

I really like the grayed out typing construct. I agree the typing is horrendous, I thought it would help clarify how the arguments are allowed, but it is just too much, see here: https://zerothi.github.io/sisl/api/generated/sisl.Geometry.html#sisl.Geometry.auc2sc I really would like it to just point to AtomsLike.

[pfebrer]

I really would like it to just point to AtomsLike.

See the trick here: https://github.com/pandas-dev/pandas/issues/33025#issuecomment-699636759

I think it would be very useful for AtomsLike and AtomsArgument.

I really like the grayed out typing construct.

This one: ?

[zerothi]

Great reference for hiding the information, lets do something like that. I'll play later.

As for the type hinting, I kind of prefer how it is shown in Geometry, no type-hints at the interface (for clarity), and an extensive type declaration in the Parameters section. I am not fully sure why your PdosPlot shows differently from Geometry...

[pfebrer]

Don't you think the typehinted signature is clear enough if you give one line to each parameter? I like it because it gives you a quick idea of what the argument expects, as in the source code.

I think this:

Is more helpful than this:

(I know the typing is missing in the argument description)

[zerothi]

The typing should be present in the argument description, I don't mind having them in the interface, IFF they are simple lines, the Geometry example is really bad since there the typing gets excessively long. If it hinders readability, I don't want it ;) Users don't really care, and if it becomes difficult to see the order of arguments, it becomes hard. So in that case the 1-line per argument is great!

[pfebrer]

Yeah I agree, I would like that the typehints are shown in the signature with 1 line per argument only if it is possible to use the trick to avoid expanding the complex typehints.

I think for users that are already familiar with type hints that might help, and also it shows that the package is type hinted, which is not clear if the typehint appears only in the description.