Add support for short signatures in autosummary #13172
Conversation
get_items() already formats the signature. Handling :nosignatures: option in the saves the signature computation cost if the signature is not wanted. Also, this prepares for more complex signature options.
This is in preparation of extending singature formating.
timhoffm
force-pushed
the
autosummary-short-signature
branch
from
b87c5bc to
cd95331
Compare
This formats functions and classes with (…) if they have arguments and () if they don't have arguments. This makes it easier to distinguish callables from attributes and properties.
timhoffm
force-pushed
the
autosummary-short-signature
branch
from
cd95331 to
df273d6
Compare
timhoffm
force-pushed
the
autosummary-short-signature
branch
from
5b082a7 to
bf01890
Compare
|
#13264 has renamed |
|
Sure, if it makes more sense to deprecate A |
|
It wasn't originally, to not force user changes. But since the renaming already does that, we can get to a cleaner state with no additional cost. |
# Conflicts: # doc/usage/extensions/autosummary.rst # sphinx/ext/autosummary/__init__.py
Since we introduced the more general ``:signatures: none` spelling, we can directly push people in this direction.
CHANGES.rst
Outdated
| pattern doesn't match any documents, via the new ``toc.glob_not_matching`` | ||
| warning sub-type. | ||
| Patch by Slawek Figiel. | ||
| * #9732: Add the new ``autodoc.mocked_object`` warnings sub-type. | ||
| * #9732: Add the new ``autodoc.mock_objects`` warnings sub-type. |
There was a problem hiding this comment.
Strange. That's of course unintended.. I possibly have messed up git when bringing in the remote upstream merge.
There was a problem hiding this comment.
Ok fixed. I'm struggling with the merge-main-into-branch workflow. I'm much more comfortable with rebases. Sorry for the confusion.
There was a problem hiding this comment.
No worries -- I tend to use the merge interface in PyCharm for tricky merges, which simplifies things greatly.
|
Thank you @timhoffm! A |
This introduces a new
:signatures:option to.. autosummary::.Possible values are:
func()if they do not have arguments andfunc(…)if they do have arguments.The new functionality here is the "short" option. This allows to distinguish properties and attributes from functions and classes without costing a lot of space for a long signature.
Note 1: Design: I've added the
:signatures:option to have a single config value instead of:shortsignatures:alongside:no-signatures:. This is also more extensible in case other signature variants come up in the future.:no-signatures:remains available for backward compatibility, but:signatures:takes precedence if given.Note 2: Tests: There are currently no tests for the signature formatting. I could add some tests for
Autosummary.get_items, but I don't understand how to set up everything in a test so that I can exercise that function. Please give a hint how to do this if tests are desired.Closes #13101.