Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Short signatures for autosummary #13101

Open
timhoffm opened this issue Nov 5, 2024 · 2 comments · May be fixed by #13172
Open

Short signatures for autosummary #13101

timhoffm opened this issue Nov 5, 2024 · 2 comments · May be fixed by #13172
Labels
extensions:autosummary type:proposal a feature suggestion

Comments

@timhoffm
Copy link
Contributor

timhoffm commented Nov 5, 2024 •
edited
Loading

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:

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:

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

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?
@timhoffm timhoffm added the type:proposal a feature suggestion label Nov 5, 2024
@electric-coder
Copy link

electric-coder commented Nov 10, 2024 •
edited
Loading

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
Copy link
Contributor Author

timhoffm commented Nov 10, 2024 •
edited
Loading

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.

@timhoffm timhoffm linked a pull request Dec 6, 2024 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
extensions:autosummary type:proposal a feature suggestion
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add support for short signatures in autosummary timhoffm/sphinx
3 participants
@timhoffm @jayaddison @electric-coder