sphinx-doc
Autodoc: add ``:canonical:`` for all object types
Feature or Bugfix
- Feature
Purpose
- Creates a common superclass for all PyObject documenters
- Moves the changes in #9026 to that superclass, so functions and methods get thir
:canonical:as well
cc @tk0miya
- Closes #5603
OK, one test fails, how should we fix it?
It happens in a newer Python (e.g. 3.9), in case of a TypeVar that’s a class attribute.
__qualname__ is not set, so the code falls back to __name__, which is wrong.
Could you let me know why do you add :canonical: options for everything? In my understanding, nobody refers the canonical functions, methods and others. I'd like to know the real usecase of this.
Everything can be initially defined in one module and be exported in another, not just classes. As you can see in the test changes, it does happen!
Also I thought that one use case of this is that automatically generated reStructuredText code referring to f'{obj.__module__}.{obj.__qualname__}' works… Only inferring it for classes leaves it broken for functions and methods.
@flying-sheep looks like this needs a rebase?
@tk0miya seems like this PR is awaiting your comment too...
Hi @AA-Turner, I’d be happy if you bring this over the finish line (and that’d be probably faster), but if you want, I could also try fixing the tests.
I'm happy with the implementation here but I haven't had time to fix the remaining tests or write any documentation -- would you have time to do so @flying-sheep? If so, I would like to get this in to v8.2.0.
A
I’m checking it out. Questions:
- 8158a1817df25e467ae211f4daa18d46e808617b is a pretty hacky way to fix builtins: that test was really wrong, now it works as expected, but do you want to keep this hack or is there a better way?
- d691a85258ebdcd52b322b0cfa1ea83280d340b3 reverts a bunch of wrong
:canonical:parameters you added in 142014eda7cee273944dae39e45e764657766ad0. Why did you add them?target.properties.Foo.prop1.fget.__qualname__ == "Foo.prop1"as expected!
Why did you add them?
I was just mechanically trying to fix test output -- no other rationale.
A