Short signatures for autosummary

[timhoffm]

autosummary has currently two options for signatures

• use the full signature, which can be very verbose
• suppress the signature completely using the :nosignatures: option. When using this, only the name is printed, so that we loose the distinction between attributes/properties and methods, example:

The first one is a property, the second one is a method with arguments, the third one is a method without arguments. (source)

I propose to add a third option with a reduced signature: It could look like this:

• methods without arguments get empty parentheses
• methods with arguments get parentheses with ellipsis:

This would convey more information without requiring much extra space.

If this is a reasonable feature, I'd start impelementing it. - Side- / implementation question. If we want this, is an additional :shortsignatures: option the way to go (which would be mutually exclusive with :nosignatures: or would one better go for a generic option :signatures: that can take values like :signatures: short , :signatures: none, which would be extensible to more signature handling variants?

[electric-coder]

This would convey more information

(...)

• methods without arguments get empty parentheses
• methods with arguments get parentheses with ellipsis:

A quick thought is that every method (unbounded doesn't exist in Python 3) has at least the self, or cls parameter; so you wouldn't be conveying much added info besides establishing a difference between functions and methods unless you arbitrate (as autodoc does) to suppress the first parameter by default.

But the Ellipsis has a semantic meaning in Python - so we have to ask: can an empty signature be overloaded with an Ellipsis? I think it can not! Thus adding the ... does keep within syntactic rules.

If this is a reasonable feature, I'd start implementing it.

I support this, it would definitely make those docs a lot better.

is an additional :shortsignatures: option the way to go (which would be mutually exclusive with :nosignatures:

A single :signatures: option with 3 XOR values would be preferable but that might break backward compatibility... (This could be solved by a long-term deprecation warning with an interim double option.)

[timhoffm]

you arbitrate (as autodoc does) to suppress the first parameter by default.

Yes, that’s the plan.

But the Ellipsis has a semantic meaning in Python - so we have to ask: can an empty signature be overloaded with an Ellipsis? I think it can not! Thus adding the ... does keep within syntactic rules.

I wouldn’t use ... but the Unicode char U+2026. This technically avoids a possible clash. Also, using the single char should make it a bit more clear it’s actually a textual ellipsis and not a code construct.