Force Sphinx 4

[alexfikl]

Was trying to see if the :canonical: thing in Sphinx 4 actually works. At least locally, this seems to generate the docs without warnings.

[alexfikl]

I was looking through the docs to see if this made anything look fishy and saw that setting autodoc_typehints = "description" makes the singledispatch-ed functions impressively useless.

Should I disable it?

[alexfikl]

8ed6c8a is unrelated and can be spun off into a separate PR (?). I just added them while trying to convince sphinx to add annotations selectively (didn't work).

[inducer]

I was looking through the docs to see if this made anything look fishy and saw that setting autodoc_typehints = "description" makes the singledispatch-ed functions impressively useless.

Yikes! Why would it remove the types from the signature? That's dumb. Let's get rid of it. (21eab4b)

Btw, I think we went through pretty much the same process with :canonical:. I was all excited about it and tried adding it, only to discover that (a) its effect is thoroughly underwhelming and (b) Sphinx 4 seems to do the right thing out of the box.

[inducer]

Also, thanks for working on this!

[inducer]

Also, why not: inducer/ci-support@e0402f6,
9581550.

[inducer]

8ed6c8a is great btw. Thanks for that. It can totally stay.

[alexfikl]

Yikes! Why would it remove the types from the signature? That's dumb. Let's get rid of it. (21eab4b)

It sort of does what it says on the tin, i.e. "description" moves the annotations from the signature to the parameter list. Unfortunately that's a pretty bad idea for singledispatch-ed functions :(

Btw, I think we went through pretty much the same process with :canonical:. I was all excited about it and tried adding it, only to discover that (a) its effect is thoroughly underwhelming and (b) Sphinx 4 seems to do the right thing out of the box.

Yeah, it seems that it adds :canonical: itself for all the autosomething directives, which is pretty nifty! The only annoying thing is that it seems to keep the full names, e.g. modepy.shapes.Simplex instead of just modepy.Simplex in the type annotations :\

[inducer]

Yeah, it seems that it adds :canonical: itself for all the autosomething directives, which is pretty nifty! The only annoying thing is that it seems to keep the full names, e.g. modepy.shapes.Simplex instead of just modepy.Simplex in the type annotations :\

IME it doesn't if you add .. currentmodule:: modepy above?

[alexfikl]

IME it doesn't if you add .. currentmodule:: modepy above?

I meant the way it shows up below, for example. That chunk of docs should have a currentmodule:: modepy above it and the docs for the Simplex class show up as modepy.Simplex, but the type annotations still have the full path.

[inducer]

OIC. But if you click, you go to modepy.Simplex, which is already huge. I imagine they'll get the type annotations fixed up eventually.

[alexfikl]

OIC. But if you click, you go to modepy.Simplex, which is already huge. I imagine they'll get the type annotations fixed up eventually.

Definitely, I'm very happy with the improvements already. Don't get to have a negative diff very often! 🎉

[alexfikl]

@inducer Potentially interesting until they update the type annotation
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-python_use_unqualified_type_names

[inducer]

@inducer Potentially interesting until they update the type annotation
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-python_use_unqualified_type_names

Thanks for the suggestion! The current state is usable though IMO, no way I'm doing another 30 PRs. :)