sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.61k stars 2.13k forks source link

Short signatures for autosummary #13101

Open timhoffm opened 2 weeks ago

timhoffm commented 2 weeks ago

autosummary has currently two options for signatures

image

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:

image

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 commented 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.)

timhoffm commented 1 week ago

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.