Skip to content
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.

Sign up for GitHub

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

Jump to bottom

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

Open
jhpalmieri opened this issue Mar 30, 2019 · 10 comments
Open

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

jhpalmieri opened this issue Mar 30, 2019 · 10 comments
Labels
c: documentation p: critical / 2 t: bug

Comments

@jhpalmieri
Copy link
Member

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
@jhpalmieri jhpalmieri added this to the sage-8.8 milestone Mar 30, 2019
@embray
Copy link
Contributor

embray commented Apr 2, 2019

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
Copy link
Member Author

comment:2

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

@slel
Copy link
Member

slel commented Jun 12, 2019

Changed keywords from none to sphinx, formatargspec, Signature

@slel slel changed the title Don't use sphinx.ext.autodoc.inspector.formatargspec anymore Use sphinx.util.inspect.Signature not sphinx.ext.autodoc.inspector.formatargspec Jun 12, 2019
@slel

This comment has been minimized.

Sign in to view
@jhpalmieri
Copy link
Member Author

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
Copy link
Contributor

embray commented Jul 3, 2019

comment:8

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

@embray embray modified the milestones: sage-8.8, sage-8.9 Jul 3, 2019
@embray
Copy link
Contributor

embray commented Dec 30, 2019

comment:9

Ticket retargeted after milestone closed

@embray embray modified the milestones: sage-8.9, sage-9.1 Dec 30, 2019
@mkoeppe mkoeppe modified the milestones: sage-9.1, sage-9.2 May 7, 2020
@mkoeppe mkoeppe modified the milestones: sage-9.2, sage-9.3 Sep 5, 2020
@mkoeppe
Copy link
Contributor

mkoeppe commented Feb 15, 2021

comment:12

See also: #31309 sage_getargspec mishandles keyword-only arguments

@mkoeppe
Copy link
Contributor

mkoeppe commented Mar 24, 2021

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.

@mkoeppe mkoeppe modified the milestones: sage-9.3, sage-9.4 Mar 24, 2021
@mkoeppe mkoeppe modified the milestones: sage-9.4, sage-9.5 Jul 19, 2021
@mkoeppe mkoeppe modified the milestones: sage-9.5, sage-9.6 Dec 14, 2021
@tobiasdiez
Copy link
Contributor

comment:17

An alternative is proposed in #30884.

@mkoeppe mkoeppe removed this from the sage-9.6 milestone May 3, 2022
@mkoeppe mkoeppe added this to the sage-9.7 milestone May 3, 2022
@mkoeppe mkoeppe modified the milestones: sage-9.7, sage-9.8 Aug 6, 2022
@mkoeppe mkoeppe modified the milestones: sage-9.8, sage-9.9 Jan 7, 2023
@nthiery nthiery mentioned this issue Jan 29, 2023
Open
@jhpalmieri jhpalmieri mentioned this issue Jul 3, 2019
Closed
@kwankyu kwankyu mentioned this issue Nov 15, 2022
Closed
kryzar pushed a commit to kryzar/sage that referenced this issue Feb 6, 2023
Trac sagemath#34730: Rebase sage_autodoc to sphinx 5.3.0
b52855e 
We rebase `sage_autodoc` to Sphinx 5.3.0.

This is a step toward eventual removal of sage_autodoc in sagemath#30893, a
customization of Sphinx autodoc extension for Sage objects.

Other related tickets are sagemath#27578. sagemath#30884, sagemath#31309, in this regard.

URL: https://trac.sagemath.org/34730
Reported by: klee
Ticket author(s): Kwankyu Lee
Reviewer(s): Tobias Diez
@mkoeppe mkoeppe removed this from the sage-10.0 milestone Mar 16, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
c: documentation p: critical / 2 t: bug
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@embray @jhpalmieri @slel @tobiasdiez @mkoeppe