Rebase sage_autodoc to sphinx 5.3.0

[kwankyu]

We rebase sage_autodoc to Sphinx 5.3.0.

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

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

CC: @kiwifb

Component: documentation

Author: Kwankyu Lee

Branch/Commit: aa74d4b

Reviewer: Tobias Diez

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

[kwankyu]

Branch: u/klee/rebase_sage_autodoc_to_sphinx_5_3_0

[kwankyu]

Author: Kwankyu Lee

[kwankyu]

Commit: 94a9718

[kwankyu]

comment:3

Setting "needs review" to build the documentation for further check.

[sagetrac-git]

Changed commit from 94a9718 to 3e917a4

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3e917a4

Remove spurious changes

[sagetrac-git]

Changed commit from 3e917a4 to aa74d4b

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

aa74d4b

More edits

[kiwifb]

comment:13

Do you have a ticket for sphinx 5.3.0 or is it backward compatible?

[kwankyu]

comment:14

Replying to François Bissey:

Do you have a ticket for sphinx 5.3.0 or is it backward compatible?

There is no difference between autodocs of sphinx 5.2.3 and 5.3.0.

[kwankyu]

comment:15

Moreover, as our old sage_autodoc (that is based on sphinx 1.8.x) still works with sphinx 5.2.3, autodoc extension seems pretty independent from the version of sphinx.

[kiwifb]

comment:16

I am fairly it has been touched here and there. But because of the ticket title I was wondering if we were doing something specific for sphinx 5.3.0. I have not checked we are compatible with sphinx 5.3.0 for example (and presumably if Antonio Rojas tested it, he didn't find/report any issues).

[kwankyu]

comment:17

Replying to François Bissey:

I am fairly it has been touched here and there. But because of the ticket title I was wondering if we were doing something specific for sphinx 5.3.0.

I just used the latest from sphinx 5.x series.

[kwankyu]

comment:18

Replying to François Bissey:

I have not checked we are compatible with sphinx 5.3.0 for example (and presumably if Antonio Rojas tested it, he didn't find/report any issues).

When I did the rebase for sphinx 1.8.x, there were many regressions, which Jeroen Demeyer detected and reported to me. If there are none (or few) this time, that is because of the efforts made then. This time it is not that difficult. Next time, hopefully it would be even easier :)

[tobiasdiez]

comment:19

LGTM.

Since you are now familiar with the code, can you maybe list the major changes of sage's autodoc in #30893 with a proposal for how to remove the modification.

[tobiasdiez]

Reviewer: Tobias Diez

[kwankyu]

comment:20

Replying to Tobias Diez:

LGTM.

Thanks.

Since you are now familiar with the code,

Well.., it was basically trial-and-errors with bits of understanding here and there :)

can you maybe list the major changes of sage's autodoc in #30893 with a proposal for how to remove the modification.

I marked in the code where modifications are made. It is easy to list them:

1. skipping lazy imports to avoid deprecation warnings
2. providing argspecs for decorators (sage_wraps)
3. dealing with nested classes
4. dealing with cached function(methods) callers
5. dealing with classcall metaclass
6. dealing with class aliases
7. using argspecs instead of signature

but sorry no proposal for how to remove them. All looks difficult. I am not sure if the aim of eventual removal of sage_autodoc is really achievable.

After #26254 merged, switching to signature seems the most urgent thing.

[tobiasdiez]

comment:21

Thanks for the summary, I've added it to #30893.

[vbraun]

Changed branch from u/klee/rebase_sage_autodoc_to_sphinx_5_3_0 to aa74d4b