Open timhoffm opened 1 week ago
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.)
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.
autosummary has currently two options for signatures
: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:
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?