fix: handle Sphinx 9.x new autodoc options key format and sentinels (#688)

* fix: handle Sphinx 9.x new autodoc options key format and sentinels

Sphinx 9.x's new non-legacy autodoc uses underscored keys
(e.g., `exclude_members`) and the `EMPTY` sentinel instead of
hyphenated keys (`exclude-members`) and the `ALL` sentinel used
by older Sphinx. This caused `:exclude-members:` to be silently
ignored by numpydoc, producing spurious `py:obj reference target
not found` warnings for excluded inherited members in nitpicky
mode.

- Update `ClassDoc.__init__` to check both `exclude_members`
  and `exclude-members` keys, and normalize `EMPTY` to `ALL`
- Update `mangle_docstrings` to use `vars()` instead of the
  deprecated Mapping interface for `_AutoDocumenterOptions`

Closes #671

* Add test

Author: jschueller

numpydoc/docscrape.py

@@ -628,8 +628,17 @@ def __init__(self, cls, doc=None, modulename="", func_doc=FunctionDoc, config=No
 
         if "sphinx" in sys.modules:
             from sphinx.ext.autodoc import ALL
+
+            try:
+                from sphinx.ext.autodoc._sentinels import EMPTY
+            except ImportError:
+                try:
+                    from sphinx.ext.autodoc import EMPTY
+                except ImportError:
+                    EMPTY = object()
         else:
             ALL = object()
+            EMPTY = object()
 
         if config is None:
             config = {}
@@ -649,7 +658,11 @@ def __init__(self, cls, doc=None, modulename="", func_doc=FunctionDoc, config=No
         _members = config.get("members", [])
         if _members is ALL:
             _members = None
-        _exclude = config.get("exclude-members", [])
+        _exclude = config.get("exclude_members")
+        if _exclude is None:
+            _exclude = config.get("exclude-members", [])
+        if _exclude is EMPTY:
+            _exclude = ALL
 
         if config.get("show_class_members", True) and _exclude is not ALL:
 

numpydoc/numpydoc.py

@@ -187,10 +187,17 @@ def mangle_docstrings(app: SphinxApp, what, name, obj, options, lines):
     }
     # TODO: Find a cleaner way to take care of this change away from dict
     # https://github.com/sphinx-doc/sphinx/issues/13942
-    try:
-        cfg.update(options or {})
-    except TypeError:
-        cfg.update(options.__dict__ or {})
+    if options is not None:
+        if isinstance(options, dict):
+            cfg.update(options)
+        elif hasattr(options, "from_directive_options"):
+            # Sphinx 9.x _AutoDocumenterOptions
+            cfg.update(vars(options))
+        else:
+            try:
+                cfg.update(options or {})
+            except TypeError:
+                cfg.update(options.__dict__ or {})
     u_NL = "\n"
     if what == "module":
         # Strip top title

numpydoc/tests/test_numpydoc.py

@@ -4,10 +4,18 @@
 from pathlib import PosixPath
 
 import pytest
+import sphinx
 from docutils import nodes
 from sphinx.ext.autodoc import ALL
 from sphinx.util import logging
 
+try:
+    from sphinx.ext.autodoc._directive_options import _AutoDocumenterOptions
+    from sphinx.ext.autodoc._sentinels import EMPTY
+except ImportError:
+    _AutoDocumenterOptions = None  # Sphinx < 9
+    EMPTY = None
+
 from numpydoc.numpydoc import (
     _clean_text_signature,
     clean_backrefs,
@@ -82,6 +90,35 @@ def test_mangle_docstrings_basic():
     assert "upper" not in [x.strip() for x in lines]
 
 
+@pytest.mark.skipif(
+    sphinx.version_info < (9, 0),
+    reason="_AutoDocumenterOptions not available",
+)
+@pytest.mark.parametrize(
+    ("kwargs", "has_rpartition", "has_upper"),
+    [
+        ({"exclude_members": {"upper"}}, True, False),
+        ({"exclude_members": EMPTY}, False, False),
+        ({}, True, True),
+    ],
+)
+def test_mangle_docstrings_exclude_members_sphinx9(kwargs, has_rpartition, has_upper):
+    """Non-regression test for #671: Sphinx 9.x _AutoDocumenterOptions with
+    underscored exclude_members key and EMPTY sentinel."""
+    s = """
+A top section before
+
+.. autoclass:: str
+    """
+
+    lines = s.split("\n")
+    options = _AutoDocumenterOptions(**kwargs)
+    mangle_docstrings(MockApp(), "class", "str", str, options, lines)
+    lines = [x.strip() for x in lines]
+    assert ("rpartition" in lines) is has_rpartition
+    assert ("upper" in lines) is has_upper
+
+
 def test_mangle_docstrings_inherited_class_members():
     # if subclass docs are rendered, this PosixPath should have Path.samefile
     p = """