-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
autodoc confused by angle brackets ("<" or ">") #12695
Comments
The deciding configuration here is autodoc's
Here the default value is
Here are 2 strange things:
So yes, I haven't tested it but if the results are as shown this is a bug. It's especially strange because default values are rarely touched and autodoc just transcribes the values textually as strings. P.S. The title of the question is misleading - if I understand the example correctly- because the default argument value you're trying to document doesn't have any greater/lesser
A screenshot would have been valuable to illustrate such strange symptoms. |
Sorry, this was an omission on my side, I have seen this with other objects (not just functions, predominantly dataclass factories) and all thy had in common was the representation containing mymodule.py: from dataclasses import dataclass
from typing import Any
@dataclass
class WithRepr:
repr: str
def __repr__(self) -> str:
return self.repr
def foo1(x: Any = WithRepr("<angle brackets>")) -> None:
pass
def foo2(x: Any = WithRepr("<")) -> None:
pass
def foo3(x: Any = WithRepr(">")) -> None:
pass |
As was said by tk0miya (emphasis mine):
and the documentation also states this:
Presently the most viable workaround is using the .. automodule:: mymodule
:members:
:undoc-members:
:exclude-members: foo
.. autofunction:: foo(a: typing.Callable[[int], int] = identity) -> int or for the shortened type using the tilde .. automodule:: mymodule
:members:
:undoc-members:
:exclude-members: foo
.. autofunction:: foo(a: ~typing.Callable[[int], int] = identity) -> int This is certain to not be a good solution for autosummary users who seek to write less |
This workaround still doesn't work with index.rst: mymodule documentation
======================
.. automodule:: mymodule
.. autofunction:: foo(a: ~typing.Callable[[int], int] = <function identity>) -> int mymodule.py: from typing import Callable
def identity[T](x: T) -> T:
return x
def foo(a: Callable[[int], int] = identity) -> int:
"""foo evaluates ``a`` at zero."""
return a(0) Result: |
@MKuranowski you didn't remove the greater |
The explicit signature from the .rst takes precedence, at least from what I have observed. And yes, removing There's something deeply wrong with processing angle brackets. I can't find any special meaning of |
That's not a good analogy because it's a solution that makes things work! Having one single clear solution (explicitly writing the signature into the rst) is good enough.
Presumably the directive argument is being parsed incorrectly, look no further if you want to assign blame for the difficulty of writing a type hint compatible signature parser for an ever changing specification. As the saying goes in the open source community: "be the change you want to see"; iow: "PRs welcome". You could also write a signature as previously explained, or use a sentinel value instead of a mutable default argument (as is generally recommended). |
Here it gets really complicated! Because when Sphinx is translating to HTML the angle brackets do have a special meaning and can break the parsing. A directive is a body element and there's not necessarily any limitation on the directive argument, if you look carefully at the docs for directive it says:
That gives custom directives plenty of latitude for how they are parsed, hence for |
Well, not with I think that in the end I will move away from autosummary and just use autodoc, not only due to this bug. This is however really painful for maintenance, as there is no single source for signatures, and programmers need to remember to update the documentation with any changes to code. |
Describe the bug
autodoc creates very verbose signatures for functions and methods, as if the tilde (
~
) sign was ignored, whenever there's a default value with an angle bracket (<
or>
) in its representation.How to Reproduce
Default configuration (as generated by
sphinx-quickstart
), but with thesphinx.ext.autodoc
extension.index.rst:
mymodule.py:
With that configuration, the generated summary looks like this:
Without the default argument value for
foo
(def foo(a: Callable[[int], int]) -> int:
, the generated summary is correct and looks like this:Environment Information
Sphinx extensions
["sphinx.ext.autodoc"]
Additional context
No response
The text was updated successfully, but these errors were encountered: