Replace sage autodoc extension by built-in one

[tobiasdiez]

Replaces sage's custom autodoc extension by the built-in one. The motivation is to add support for typing information in the documentation in #30894.

The following customizations need to be removed for this:

• providing argspecs for decorators (sage_wraps): #30884
• using argspecs instead of signature
• dealing with cached function(methods) callers
• dealing with nested classes
• dealing with classcall metaclass
• dealing with class aliases
• skipping lazy imports to avoid deprecation warnings

Depends on #30884

CC: @jhpalmieri @kwankyu

Component: documentation

Work Issues: Make docbuild pass

Author: Tobias Diez

Branch/Commit: public/documentation/replaceautodoc @ ca98b7a

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

[tobiasdiez]

Author: Tobias Diez

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

f149da6

Replace sage autodoc extension by built-in one

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 2220595 to f149da6

[tobiasdiez]

Description changed:

--- 
+++ 
@@ -1,4 +1,4 @@
-Replaces sage's custom autodoc extension by the built-in one. 
+Replaces sage's custom autodoc extension by the built-in one. The motivation is to add support for typing information in the documentation in #30894.

 For some reason, my local installation only wants to build the documentation for the manifold package. For this, I verified that the newly generated documentation is on par with the old one. This was the case except for parameters added with the `@output` decorator. This should be fixed with #30884.
 Please let me know if there are other customization in the sage autodoc file except for the `sage_wraps` decorator support. 

[jhpalmieri]

comment:6

Building the docs fails immediately for me, because text roles like :arxiv:, :trac:, etc. are no longer defined.

I think it would be better, at least as a first step, to update sage_autodoc to incorporate the recent changes in Sphinx's autodoc.

[jhpalmieri]

comment:7

My understanding is that one of the main reasons for using our own version of autodoc is to be able to include Cython files in the documentation, and this requires customization of the introspection code. So that is something you should test when experimenting with this: how is autodoc working on Cython files?

[tobiasdiez]

comment:8

Thanks for the input @jhpalmieri.

Building the docs fails immediately for me, because text roles like :arxiv:, :trac:, etc. are no longer defined.

That should be fixed now.

I think it would be better, at least as a first step, to update sage_autodoc to incorporate the recent changes in Sphinx's autodoc.

I tried rebasing first, but there were quite a few changes which made it rather difficult. So I thought replacing it completely, and then implement the necessary changes elsewhere would be easier.

should test when experimenting with this: how is autodoc working on Cython files?

I will do so! I just figured out how to convince sage to produce the documentation for something else then the manifold package. After playing around a bit, I realized that there might be quite some changes necessary (e.g. instancedoc doesn't play nicely with Python's inspect). Will keep you updated.

[tobiasdiez]

Work Issues: Make docbuild pass

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

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

ca98b7a

Fix extlinks

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from f149da6 to ca98b7a

[mkoeppe]

comment:10

Setting new milestone based on a cursory review of ticket status, priority, and last modification date.

[mkoeppe]

comment:11

Setting a new milestone for this ticket based on a cursory review.

[tobiasdiez]

Description changed:

--- 
+++ 
@@ -1,4 +1,10 @@
 Replaces sage's custom autodoc extension by the built-in one. The motivation is to add support for typing information in the documentation in #30894.

-For some reason, my local installation only wants to build the documentation for the manifold package. For this, I verified that the newly generated documentation is on par with the old one. This was the case except for parameters added with the `@output` decorator. This should be fixed with #30884.
-Please let me know if there are other customization in the sage autodoc file except for the `sage_wraps` decorator support. 
+The following customizations need to be removed for this:
+- skipping lazy imports to avoid deprecation warnings
+- providing argspecs for decorators (sage_wraps): #30884
+- dealing with nested classes
+- dealing with cached function(methods) callers
+- dealing with classcall metaclass
+- dealing with class aliases
+- using argspecs instead of signature 

[kwankyu]

Description changed:

--- 
+++ 
@@ -1,10 +1,18 @@
 Replaces sage's custom autodoc extension by the built-in one. The motivation is to add support for typing information in the documentation in #30894.

 The following customizations need to be removed for this:
-- skipping lazy imports to avoid deprecation warnings
+
 - providing argspecs for decorators (sage_wraps): #30884
+- using argspecs instead of signature 
+- dealing with cached function(methods) callers
 - dealing with nested classes
-- dealing with cached function(methods) callers
 - dealing with classcall metaclass
 - dealing with class aliases
-- using argspecs instead of signature 
+- skipping lazy imports to avoid deprecation warnings
+
+
+
+
+
+
+