Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
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
ENH: enable multiline signatures when too long. #11011
ENH: enable multiline signatures when too long. #11011
Changes from 26 commits
82f1b98
8d6dfba
581433b
d3ec233
1229b66
ec713e9
85ff493
8ca560d
9ec4698
b93ecf0
3b110ce
234acd6
7c016c9
5b8735d
1ca68b0
8e198f3
25ae353
d6b2dac
af77cad
ea89180
5cc07d6
caff655
b71b06d
88c2e09
4258fd5
6e6261c
9c52eae
2d9ad80
0bc3b68
2c0da6a
bba2b51
d8df099
d18f973
d803e68
3753e7e
eb63da6
53e882f
d7508a0
b665647
ada9d00
ed7fac8
1475f5f
9b9e694
691a780
4deb58c
48d2ccb
b065ab7
8d42ac1
2b864fe
fa97a15
d787002
707650f
b1cb1b3
8308742
e6ef3c2
dfd0075
bfab7ea
26551bc
9d03de0
b3e5662
592c86c
1af1a2e
69dba4b
2918995
d58b63c
b866b88
c6cf460
b18c481
4b47e79
a652d3e
bcba5f6
3243f9d
93bdb8d
417db1f
c4e9c62
57004e3
88cfe5a
9ce3e34
3379337
98f1803
ef7adde
1ad0981
e36c811
ea30441
2d604b9
71f5a8a
e948563
d2b3459
bfc353e
0c54703
a1b031f
a0f5d9b
a8a9be9
3b34e30
2c1f83a
9c625f1
5866fe6
3bef7e4
30041a6
8037a5b
2a85b9e
35424ea
db91327
1a44553
0c4fdb8
36183f5
f2d1574
370cd0e
50ac9a6
585b2b9
File filter
Filter by extension
Conversations
Jump to
There are no files selected for viewing
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've mixed feelings on this, how would you feel about just always breaking to one line per argument and having a global (boolean) option to preserve single lines?
A
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As a potential user of this, I'd really like to be able to specify a threshold (and have Sphinx ship with a sensible default...)
I don't want simple functions with one or two args having their signatures split across lines, and I have an even enough mix that a boolean is going to cause an annoying amount of work no matter which way it is set....
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tend to agree with @cjw296 -- something like https://installer.pypa.io/en/stable/api/__init__/ should stay on all-entries-on-one-line (instead of breaking that up) because they fit, while something like https://testfixtures.readthedocs.io/en/latest/api.html#testfixtures.compare should get split across multiple lines.
Using the number of characters in the signature is the natural piece for enabling that behaviour with a clear semantic; and the explicit opt-outs on a per-project and per-signature level are also useful to get the exact semantics that an author might want.
To answer the how I'd feel question: As a user, I'd be... annoyed/frustrated with a change as proposed by @AA-Turner; especially if the
installer
API example would get broken up into multiple lines after a Sphinx minor/patch update. As a theme author, I'd... implore you to, should you decide to change the default behaviour like that, to handle it like a backwards-incompatible change to a public Python API of this project. :)There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
re "When negative (the default), there is no maximum, no line break will be introduced no matter how long the signature".
I assume that if the html theme sets a maximum body width (either through a configuration parameter or hardcoded), then the negative default value will not override this, i.e. the signature will be wrapped based on html theme. Perhaps that could be noted/documented in the description of the
python_maximum_signature_line_length
parameter.For example, see
basic
html theme'sbody_max_width
parameter.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@emezh yes indeed, you can see the line breaks introduced by
python_maximum_signature_line_length
as hard-wrapping, while the soft-wrapping in the view (here the HTML render) can wrap lines independently. I did not make this clear at all in the doc though, so I clarified this point in my last commit (0bc3b68)