Use sphinx.util.inspect.Signature not sphinx.ext.autodoc.inspector.formatargspec

[jhpalmieri]

After upgrading to Sphinx 1.8.5 in #26451, Sphinx's function formatargspec is deprecated, so we should not use anymore it in src/sage_setup/docbuild/ext/sage_autodoc.py.

The deprecation warning advises to replace the use of sphinx.ext.autodoc.inspector.formatargspec by that of sphinx.util.inspect.Signature.

For ordinary Python functions, we may be able to change formatargspec(my_func, *argspec) to Signature(my_func).format_args(). I don't think this works with Cython functions, though.

CC: @kiwifb @jdemeyer @slel @strogdon @tobiasdiez

Component: documentation

Keywords: sphinx, formatargspec, Signature

Issue created by migration from https://trac.sagemath.org/ticket/27578

[embray]

comment:1

The Signature class is new in Python 3, though there exists a backport of it for Python 2 so we'd have to add the backport as a depency so long as we still support Python 2. Obviously adding the backport is no big deal. I've used it before and it works fine. It's not a bad idea, since the Signature interface is much nicer in general than inspect.getargspec.

[jhpalmieri]

comment:2

Sphinx has its own Signature class (in sphinx.util.inspect), and that's what I was thinking about using.

[slel]

Changed keywords from none to sphinx, formatargspec, Signature

[slel]

Description changed:

--- 
+++ 
@@ -1,3 +1,6 @@
 After upgrading to Sphinx 1.8.5 in #26451, Sphinx's function `formatargspec` is deprecated, so we should not use anymore it in `src/sage_setup/docbuild/ext/sage_autodoc.py`.

+The deprecation warning advises to replace the use of `sphinx.ext.autodoc.inspector.formatargspec`
+by that of `sphinx.util.inspect.Signature`.
+
 For ordinary Python functions, we may be able to change `formatargspec(my_func, *argspec)` to `Signature(my_func).format_args()`. I don't think this works with Cython functions, though.

[jhpalmieri]

comment:7

The proposed changes at #27971 get rid of the deprecation warnings. We can leave this open in case it is worthwhile to use Sphinx's Signature or Python 3's Signature. (And maybe we should use those in sageinspect.py, too?)

[embray]

comment:8

Moving open critical and blocker issues to the next release milestone (optimistically).

[embray]

comment:9

Ticket retargeted after milestone closed

[mkoeppe]

comment:12

See also: #31309 sage_getargspec mishandles keyword-only arguments

[mkoeppe]

comment:13

Sage development has entered the release candidate phase for 9.3. Setting a new milestone for this ticket based on a cursory review of ticket status, priority, and last modification date.

[tobiasdiez]

comment:17

An alternative is proposed in #30884.