gh-38957: rebase sage_autodoc to sphinx 8.1.3
    
`sage_autodoc.py` is not currently working with sphinx 8.1+. In
particular `warningiserror` has mostly been removed. From logs generated
by sphinx:
```
# Platform:         linux; (Linux-6.6.58-gentoo-dist-x86_64-Intel-R-
_Core-TM-_i7-9700_CPU_@_3.00GHz-with-glibc2.40)
# Sphinx version:   8.1.3
# Python version:   3.12.7 (CPython)
# Docutils version: 0.21.2
# Jinja2 version:   3.1.4
# Pygments version: 2.18.0

# Last messages:
#   index
#
#
#   reading sources... [  8%]
#   options
#
#
#   reading sources... [ 11%]
#   sage/misc/trace
#

# Loaded extensions:
#   sphinx.ext.mathjax (8.1.3)
#   alabaster (1.0.0)
#   sphinxcontrib.applehelp (2.0.0)
#   sphinxcontrib.devhelp (2.0.0)
#   sphinxcontrib.htmlhelp (2.1.0)
#   sphinxcontrib.serializinghtml (2.0.0)
#   sphinxcontrib.qthelp (2.0.0)
#   sage_docbuild.ext.inventory_builder (unknown version)
#   sage_docbuild.ext.multidocs (unknown version)
#   sphinx.ext.autodoc.preserve_defaults (8.1.3)
#   sphinx.ext.autodoc.type_comment (8.1.3)
#   sphinx.ext.autodoc.typehints (8.1.3)
#   sage_docbuild.ext.sage_autodoc (8.1.3)
#   sphinx.ext.todo (8.1.3)
#   sphinx.ext.extlinks (8.1.3)
#   sphinx.ext.linkcode (8.1.3)
#   sphinx_copybutton (0.5.2)
#   sphinx_inline_tabs (2023.04.21)
#   IPython.sphinxext.ipython_directive (unknown version)
#   matplotlib.sphinxext.plot_directive (3.9.2)
#   jupyter_sphinx (0.5.3)

# Traceback:
Traceback (most recent call last):
  File "/usr/lib/python3.12/site-packages/sphinx/cmd/build.py", line
514, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/lib/python3.12/site-packages/sphinx/application.py", line
381, in build
    self.builder.build_update()
  File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py",
line 358, in build_update
    self.build(
  File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py",
line 385, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py",
line 502, in read
    self._read_serial(docnames)
  File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py",
line 567, in _read_serial
    self.read_doc(docname)
  File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py",
line 630, in read_doc
    publisher.publish()
  File "/usr/lib/python3.12/site-packages/docutils/core.py", line 234,
in publish
    self.document = self.reader.read(self.source, self.parser,
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/sphinx/io.py", line 106, in
read
    self.parse()
  File "/usr/lib/python3.12/site-packages/docutils/readers/__init__.py",
line 76, in parse
    self.parser.parse(self.input, document)
  File "/usr/lib/python3.12/site-packages/sphinx/parsers.py", line 85,
in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2790, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
                   ^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2359, in explicit_markup
    self.explicit_list(blank_finish)
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2384, in explicit_list
    newline_offset, blank_finish = self.nested_list_parse(
                                   ^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 316, in nested_list_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-packages/docutils/statemachine.py",
line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2662, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2369, in
explicit_construct
    return method(self, expmatch)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2106, in directive
    return self.run_directive(
           ^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/docutils/parsers/rst/states.py", line 2156, in run_directive
    result = directive_instance.run()
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/sphinx/ext/autodoc/directive.py", line 139, in run
    documenter.generate(more_content=self.content)
  File "/usr/lib/python3.12/site-
packages/sage_docbuild/ext/sage_autodoc.py", line 941, in generate
    if not self.import_object():
           ^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/sage_docbuild/ext/sage_autodoc.py", line 1073, in import_object
    ret = super().import_object(raiseerror)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.12/site-
packages/sage_docbuild/ext/sage_autodoc.py", line 479, in import_object
    ret = import_object(self.modname, self.objpath, self.objtype,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: import_object() got an unexpected keyword argument
'warningiserror'
```

This PR rebase sage_autodoc to the level of sphinx 8.1.3 while
preserving the previous compatibility for python3.9. Some more
compatibility fix may have to be added.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.
    
URL: #38957
Reported by: François Bissey
Reviewer(s):

Author: Release Manager

src/sage_docbuild/ext/sage_autodoc.py

@@ -35,6 +35,8 @@
 - François Bissey (2024-08-24): rebased on Sphinx 8.0.2
 
 - François Bissey (2024-09-10): Tweaks to support python 3.9 (and older sphinx) as well
+
+- François Bissey (2024-11-12): rebased on Sphinx 8.1.3 (while trying to keep python 3.9 compatibility)
 """
 
 from __future__ import annotations
@@ -44,7 +46,7 @@
 import sys
 import re
 from inspect import Parameter, Signature
-from typing import TYPE_CHECKING, Any, ClassVar, NewType, TypeVar
+from typing import TYPE_CHECKING, Any, NewType, TypeVar
 
 from docutils.statemachine import StringList
 
@@ -86,11 +88,19 @@ def getdoc(obj, *args, **kwargs):
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
     from types import ModuleType
+    from typing import ClassVar, Literal, TypeAlias
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
     from sphinx.ext.autodoc.directive import DocumenterBridge
 
+    _AutodocObjType = Literal[
+        'module', 'class', 'exception', 'function', 'method', 'attribute'
+    ]
+    _AutodocProcessDocstringListener: TypeAlias = Callable[
+        [Sphinx, _AutodocObjType, str, Any, dict[str, bool], list[str]], None
+    ]
+
 logger = logging.getLogger(__name__)
 
 
@@ -225,15 +235,17 @@ def merge_members_option(options: dict) -> None:
 
 # Some useful event listener factories for autodoc-process-docstring.
 
-def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
+def cut_lines(
+    pre: int, post: int = 0, what: Sequence[str] | None = None
+) -> _AutodocProcessDocstringListener:
     """Return a listener that removes the first *pre* and last *post*
     lines of every docstring.  If *what* is a sequence of strings,
     only docstrings of a type in *what* will be processed.
 
     Use like this (e.g. in the ``setup()`` function of :file:`conf.py`)::
 
        from sphinx.ext.autodoc import cut_lines
-       app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
+       app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))
 
     This can (and should) be used in place of ``automodule_skip_lines``.
     """
@@ -250,9 +262,22 @@ def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable:
     #
     #     ... in place of ``automodule_skip_lines``.
     # -------------------------------------------------------------------------
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
-                ) -> None:
-        if what and what_ not in what:
+    if not what:
+        what_unique: frozenset[str] = frozenset()
+    elif isinstance(what, str):  # strongly discouraged
+        what_unique = frozenset({what})
+    else:
+        what_unique = frozenset(what)
+
+    def process(
+        app: Sphinx,
+        what_: _AutodocObjType,
+        name: str,
+        obj: Any,
+        options: dict[str, bool],
+        lines: list[str],
+    ) -> None:
+        if what_unique and what_ not in what_unique:
             return
         del lines[:pre]
         if post:
@@ -271,7 +296,7 @@ def between(
     what: Sequence[str] | None = None,
     keepempty: bool = False,
     exclude: bool = False,
-) -> Callable:
+) -> _AutodocProcessDocstringListener:
     """Return a listener that either keeps, or if *exclude* is True excludes,
     lines between lines that match the *marker* regular expression.  If no line
     matches, the resulting docstring would be empty, so no change will be made
@@ -282,8 +307,14 @@ def between(
     """
     marker_re = re.compile(marker)
 
-    def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: list[str],
-                ) -> None:
+    def process(
+        app: Sphinx,
+        what_: _AutodocObjType,
+        name: str,
+        obj: Any,
+        options: dict[str, bool],
+        lines: list[str],
+    ) -> None:
         if what and what_ not in what:
             return
         deleted = 0
@@ -308,7 +339,7 @@ def process(app: Sphinx, what_: str, name: str, obj: Any, options: Any, lines: l
 
 # This class is used only in ``sphinx.ext.autodoc.directive``,
 # But we define this class here to keep compatibility (see #4538)
-class Options(dict):
+class Options(dict[str, Any]):
     """A dict/attribute hybrid that returns None on nonexisting keys."""
 
     def copy(self) -> Options:
@@ -476,9 +507,10 @@ def import_object(self, raiseerror: bool = False) -> bool:
         """
         with mock(self.config.autodoc_mock_imports):
             try:
-                ret = import_object(self.modname, self.objpath, self.objtype,
-                                    attrgetter=self.get_attr,
-                                    warningiserror=self.config.autodoc_warningiserror)
+                ret = import_object(
+                    self.modname, self.objpath, self.objtype,
+                    attrgetter=self.get_attr,
+                )
                 self.module, self.parent, self.object_name, self.object = ret
                 if ismock(self.object):
                     self.object = undecorate(self.object)
@@ -1145,7 +1177,8 @@ def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
                 else:
                     logger.warning(__('missing attribute mentioned in :members: option: '
                                       'module %s, attribute %s'),
-                                   safe_getattr(self.object, '__name__', '???', name),
+                                   safe_getattr(self.object, '__name__', '???'),
+                                   name,
                                    type='autodoc')
             return False, ret
 
@@ -2179,7 +2212,7 @@ def import_object(self, raiseerror: bool = False) -> bool:
             # annotation only instance variable (PEP-526)
             try:
                 with mock(self.config.autodoc_mock_imports):
-                    parent = import_module(self.modname, self.config.autodoc_warningiserror)
+                    parent = import_module(self.modname)
                     annotations = get_type_hints(parent, None,
                                                  self.config.autodoc_type_aliases,
                                                  include_extras=True)
@@ -2629,9 +2662,10 @@ def import_object(self, raiseerror: bool = False) -> bool:
         except ImportError as exc:
             try:
                 with mock(self.config.autodoc_mock_imports):
-                    ret = import_object(self.modname, self.objpath[:-1], 'class',
-                                        attrgetter=self.get_attr,  # type: ignore[attr-defined]
-                                        warningiserror=self.config.autodoc_warningiserror)
+                    ret = import_object(
+                        self.modname, self.objpath[:-1], 'class',
+                        attrgetter=self.get_attr,  # type: ignore[attr-defined]
+                    )
                     parent = ret[3]
                     if self.is_runtime_instance_attribute(parent):
                         self.object = self.RUNTIME_INSTANCE_ATTRIBUTE
@@ -2676,16 +2710,17 @@ def is_uninitialized_instance_attribute(self, parent: Any) -> bool:
         return self.objpath[-1] in annotations
 
     def import_object(self, raiseerror: bool = False) -> bool:
-        """Check the exisitence of uninitialized instance attribute when failed to import
+        """Check the existence of uninitialized instance attribute when failed to import
         the attribute.
         """
         try:
             return super().import_object(raiseerror=True)  # type: ignore[misc]
         except ImportError as exc:
             try:
-                ret = import_object(self.modname, self.objpath[:-1], 'class',
-                                    attrgetter=self.get_attr,  # type: ignore[attr-defined]
-                                    warningiserror=self.config.autodoc_warningiserror)
+                ret = import_object(
+                    self.modname, self.objpath[:-1], 'class',
+                    attrgetter=self.get_attr,  # type: ignore[attr-defined]
+                )
                 parent = ret[3]
                 if self.is_uninitialized_instance_attribute(parent):
                     self.object = UNINITIALIZED_ATTR
@@ -2760,9 +2795,7 @@ def can_document_member(
         if isinstance(type(member), ClasscallMetaclass):
             return True
         # ---------------------------------------------------------------------
-        if not inspect.isroutine(member) and not isinstance(member, type):
-            return True
-        return False
+        return not inspect.isroutine(member) and not isinstance(member, type)
 
     def document_members(self, all_members: bool = False) -> None:
         pass
@@ -2918,7 +2951,7 @@ def can_document_member(
             return False
 
     def import_object(self, raiseerror: bool = False) -> bool:
-        """Check the exisitence of uninitialized instance attribute when failed to import
+        """Check the existence of uninitialized instance attribute when failed to import
         the attribute.
         """
         ret = super().import_object(raiseerror)
@@ -2991,9 +3024,14 @@ def _get_property_getter(self) -> Callable | None:
 
 def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
     """Alternative getattr() for types"""
-    for typ, func in app.registry.autodoc_attrgettrs.items():
-        if isinstance(obj, typ):
-            return func(obj, name, *defargs)
+    try:
+        for typ, func in app.registry.autodoc_attrgetters.items():
+            if isinstance(obj, typ):
+                return func(obj, name, *defargs)
+    except AttributeError:
+        for typ, func in app.registry.autodoc_attrgettrs.items():
+            if isinstance(obj, typ):
+                return func(obj, name, *defargs)
 
     return safe_getattr(obj, name, *defargs)